Image Uploads

You can upload your own images to the API. This is useful if you want to use the API to analyze your own images, or if you want to create a private collection of images.

There are two ways to upload images:

1. Asynchronous Upload & Polling: The standard method. The upload returns immediately, and analysis happens in the background.
2. Synchronous Upload: The request stays open until the image has been fully analyzed and processed.`

Regardless of the method, you can check your current usage and limits via the Quota endpoint.

---

---

1. Upload and Poll until complete

This is an asynchronous upload method. The image is queued for analysis and optimization, and you receive a response immediately with a links.status URL. Poll that URL to track progress until processing is complete.

This approach is ideal when you want to return control to your user quickly while background processing handles breed detection, safety checks, and image optimization.

Endpoint: POST /v1/images/upload

Parameters

Parameter	Type	Description
file	File	The image file to upload (Multipart Form Data).
type	String	Upload type: FILE or base64.
image	String	Base64 encoded image data (when not using file upload).
sub_id	String	Optional. A custom ID to group your images (e.g., user ID).
height	Number	Optional. Resize height in pixels.
width	Number	Optional. Resize width in pixels.

Example Request (Multipart)

curl --request POST \
  --url https://api.thedogapi.com/v1/images/upload \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@/path/to/your/image.jpg' \
  --form 'sub_id=my-user-123'

Response

The initial response returns image metadata. The status will likely be to_be_reviewed while processing. Use the links.status URL to poll for completion.

{
    "id": "xn21",
    "url": "https://cdn2.thedogapi.com/images/xn21.jpg",
    "width": 500,
    "height": 400,
    "original_filename": "dog.jpg",
    "pending": 1,
    "approved": 0
}

Checking Status

Poll this endpoint until the status is no longer to_be_reviewed.

Endpoint: GET /v1/images/:image_id/status

curl --request GET \
  --url https://api.thedogapi.com/v1/images/xn21/status \
  --header 'x-api-key: YOUR_API_KEY'

Status Values

Status	Description
to_be_reviewed	Image is still being processed (keep polling).
clean	Image approved and ready to use.
unsafe	Image rejected due to safety check failure.
flagged	Image requires manual review.
labelled	Image has been labelled and ready to use.

Try It: Async Upload

🎮 Interactive DemoOpen in new tab ↗

📦 Source Code: View on GitHub

---

2. Synchronous Upload

Use this endpoint if your application needs the analysis results (like tags, breed detection, or moderation status) immediately before proceeding.

However you must use the https://upload.thedogapi.com domain for this endpoint, not the standard https://api.thedogapi.com domain.

Endpoint: POST https://upload.thedogapi.com/v1/images/upload-sync

[!NOTE] This request may take up to 60 seconds to complete depending on the depth of analysis required.

Parameters

Parameter	Type	Description
file	File	The image file to upload (Multipart Form Data).
type	String	Upload type: FILE or base64.
image	String	Base64 encoded image data (when not using file upload).
sub_id	String	Optional. A custom ID to group your images (e.g., user ID).

Example Request

curl --request POST \
  --url https://upload.thedogapi.com/v1/images/upload-sync \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@/path/to/your/image.jpg'

Response

The response will contain the full analysis results, including tags and breed information if detected.

{
  "id": "abc123xyz",
  "url": "https://cdn.thedogapi.com/images/abc123xyz.jpg",
  "width": 800,
  "height": 600,
  "review_status": "clean",
  "tags": [
    { "name": "dog" },
    { "name": "golden retriever" }
  ],
  "breeds": [
    { "id": 1, "name": "Golden Retriever" }
  ]
}

Try It: Sync Upload

🎮 Interactive DemoOpen in new tab ↗

📦 Source Code: View on GitHub

---

3. Quota & Limits

You can check your account's upload limits and current usage at any time.

Endpoint: GET /v1/accounts/quota

Example Request

curl --location 'https://api.thedogapi.com/v1/accounts/quota' \
  --header 'x-api-key: YOUR_API_KEY'

Response

{
    "quota": 5,
    "usage": 1,
    "remaining": 4
}

• quota: The total number of images you can upload this billing period.
• usage: The number of images you have uploaded so far.
• remaining: The number of uploads left.