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: 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. Asynchronous Upload

Use this endpoint for a quick response. You will receive a pending status, and you can poll for completion.

Endpoint: POST /v1/images/upload

Parameters

Parameter	Type	Description
file	File	The image file to upload (Multipart Form Data).
sub_id	String	Optional. A custom ID to group your images (e.g., user ID).

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

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

If the image requires analysis, pending will be 1 (true). You can check the status later.

Checking Status

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'

---

2. Synchronous Upload

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

Endpoint: POST /v1/images/upload-sync

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

Parameters

Same as standard upload (file, sub_id), but you can also provide type, height, width for resizing.

Example Request

curl --request POST \
  --url https://api.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" }
  ]
}

---

3. Quota & Limits

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

Endpoint: GET /v1/accounts/me/quota

Example Request

curl --location 'https://api.thedogapi.com/v1/accounts/me/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.