Skip to main content

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​

ParameterTypeDescription
fileFileThe image file to upload (Multipart Form Data).
sub_idStringOptional. 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.