Sign In Get Started

Images API

API endpoints for uploading, downloading, and managing images.

Images are the core data in Pictograph. These endpoints allow you to upload new images, download existing ones, and manage image metadata.

Get Image Metadata

GET /api/v1/developer/images/{id}/metadata

Get metadata for a specific image.

Parameters

Parameter Type Description
include_annotations boolean Include annotations in response (default: false)

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
image = client.images.get("{{IMAGE_ID}}", include_annotations=True)

print(f"Filename: {image['filename']}")
print(f"Size: {image['width']}x{image['height']}")
print(f"Annotations: {image['annotation_count']}")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}/metadata",
    headers={"X-API-Key": "{{API_KEY}}"},
    params={"include_annotations": True}
)
image = response.json()
curl "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}/metadata?include_annotations=true" \
  -H "X-API-Key: {{API_KEY}}"
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}/metadata?include_annotations=true",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const image = await response.json();
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}/metadata?include_annotations=true", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
Response Click to collapse Click to expand
JSON 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "scene_001.jpg",
  "width": 1920,
  "height": 1080,
  "file_size": 245760,
  "mime_type": "image/jpeg",
  "annotation_count": 5,
  "status": "complete",
  "created_at": "2024-01-15T10:30:00Z",
  "annotations": [...]  // If include_annotations=true
}

Download Image

GET /api/v1/developer/images/{id}

Download the image file as a binary stream.

Response

Returns the image file with appropriate Content-Type header.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
client.images.download("{{IMAGE_ID}}", output_path="./downloaded_image.jpg")
import requests

response = requests.get(
    "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}",
    headers={"X-API-Key": "{{API_KEY}}"}
)

with open("downloaded_image.jpg", "wb") as f:
    f.write(response.content)
curl https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}} \
  -H "X-API-Key: {{API_KEY}}" \
  -o downloaded_image.jpg
const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}",
  { headers: { "X-API-Key": "{{API_KEY}}" } }
);
const blob = await response.blob();

// In browser: create download link
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'downloaded_image.jpg';
a.click();
req, _ := http.NewRequest("GET",
    "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

file, _ := os.Create("downloaded_image.jpg")
defer file.Close()
io.Copy(file, resp.Body)

Upload Image

POST /api/v1/developer/images/upload

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
image = client.images.upload("{{DATASET_ID}}", "./image.jpg")
import requests

with open("./image.jpg", "rb") as f:
    response = requests.post(
        "https://api.pictograph.io/api/v1/developer/images/upload",
        headers={"X-API-Key": "{{API_KEY}}"},
        files={"file": f},
        data={"dataset_id": "{{DATASET_ID}}"}
    )
image = response.json()
curl -X POST https://api.pictograph.io/api/v1/developer/images/upload \
  -H "X-API-Key: {{API_KEY}}" \
  -F "dataset_id={{DATASET_ID}}" \
  -F "file=@image.jpg"
const formData = new FormData();
formData.append('dataset_id', '{{DATASET_ID}}');
formData.append('file', fileInput.files[0]);

const response = await fetch(
  "https://api.pictograph.io/api/v1/developer/images/upload",
  {
    method: "POST",
    headers: { "X-API-Key": "{{API_KEY}}" },
    body: formData
  }
);
file, _ := os.Open("./image.jpg")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
writer.WriteField("dataset_id", "{{DATASET_ID}}")
part, _ := writer.CreateFormFile("file", "image.jpg")
io.Copy(part, file)
writer.Close()

req, _ := http.NewRequest("POST",
    "https://api.pictograph.io/api/v1/developer/images/upload", body)
req.Header.Set("X-API-Key", "{{API_KEY}}")
req.Header.Set("Content-Type", writer.FormDataContentType())
http.DefaultClient.Do(req)

Delete Image

DELETE /api/v1/developer/images/{id}

Parameters

Parameter Type Description
permanent boolean If false (default), archives the image. If true, permanently deletes.

Example

from pictograph import Client

client = Client(api_key="{{API_KEY}}")
client.images.delete("{{IMAGE_ID}}")
import requests

requests.delete(
    "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}",
    headers={"X-API-Key": "{{API_KEY}}"}
)
curl -X DELETE https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}} \
  -H "X-API-Key: {{API_KEY}}"
await fetch(
  "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}",
  {
    method: "DELETE",
    headers: { "X-API-Key": "{{API_KEY}}" }
  }
);
req, _ := http.NewRequest("DELETE",
    "https://api.pictograph.io/api/v1/developer/images/{{IMAGE_ID}}", nil)
req.Header.Set("X-API-Key", "{{API_KEY}}")
http.DefaultClient.Do(req)
Copied to clipboard