Skip to main content
POST
/
api
/
v1
/
extract-image
Extract text from image
curl --request POST \
  --url https://app.dumplingai.com/api/v1/extract-image \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inputMethod": "url",
  "images": [
    "https://example.com/receipt.jpg",
    "https://example.com/menu.png"
  ],
  "prompt": "Summarize the totals and highlight any discounts.",
  "jsonMode": true
}'
{
  "results": "<string>",
  "prompt": "<string>",
  "imageCount": 123,
  "creditUsage": 123
}

Extract Image API Documentation

Description

This endpoint extracts structured data from image files based on a user-defined prompt. It supports input via URL or base64-encoded image content and uses vision-capable Large Language Models (LLMs) to interpret and extract relevant information from the images.

Endpoint

POST https://app.dumplingai.com/api/v1/extract-image

Headers

  • Content-Type: application/json
  • Authorization: Bearer <API_KEY> (required)

Request Body

{
  "inputMethod": "string", // Required. Either "url" or "base64".
  "images": ["string"], // Required. Array of URLs or base64-encoded image contents.
  "prompt": "string", // Required. The prompt describing the data to extract.
  "jsonMode": boolean // Optional. Whether to return the result in JSON format. Default: false.
}

Responses

Success (200)

Returns the extracted data based on the provided prompt, along with additional information.
{
  "results": "string", // Extracted data based on the prompt
  "prompt": "string", // The original prompt used for extraction
  "imageCount": number, // Number of images processed
  "creditUsage": number // Total credits used for this request
}
  • Content-Type: application/json
  • X-RateLimit-Limit: The rate limit for the user.
  • X-RateLimit-Remaining: The remaining number of requests for the user.

Bad Request (400)

Returned if the request is invalid or the total file size exceeds the limit.
{
  "error": "Error message describing the issue"
}

Unauthorized (401)

Returned if the API key is invalid or missing.
{
  "error": "Invalid or missing Authorization header"
}

Internal Server Error (500)

Returned if there’s an error during the image extraction process.
{
  "error": "Failed to extract image data: [error details]"
}

Example Request

curl -X POST https://app.dumplingai.com/api/v1/extract-image \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "inputMethod": "url",
  "images": ["https://example.com/sample-image.jpg"],
  "prompt": "Describe the main elements in this image.",
  "jsonMode": false
}'

Notes

  • The maximum total file size for all images combined is 100MB.
  • The maximum file size for a single image is 20MB.
  • The maximum number of images that can be processed in a single request is 3000.
  • The maximum output is 8,192 tokens.
  • Credit usage:
    • Base cost: 10 credits
    • Additional 1 credit per image processed
  • The total credit usage is returned in the response as creditUsage.
  • If using the URL method, ensure the image is publicly accessible.
  • The jsonMode parameter determines whether the output is formatted as JSON (true) or plain text (false).
  • Supported image formats: PNG, JPEG, WebP, HEIC, HEIF. Other formats will be automatically converted to PNG.
  • Temporary files are created during processing and are deleted after use.
  • You can get a list of supported image formats by calling:
GET /api/v1/extract-image

Rate Limiting

Rate limit headers (X-RateLimit-Limit and X-RateLimit-Remaining) are included in the response to indicate the user’s current rate limit status.

Error Handling

  • If the required parameters (images or prompt) are missing, a 400 Bad Request error is returned.
  • If the total file size exceeds 100MB, a 400 Bad Request error is returned.
  • If there’s an error during extraction, a 500 Internal Server Error is returned with details about the failure.

Security and Privacy

  • Uploaded images are temporarily stored and then deleted after processing.
  • The endpoint uses the Gemini 1.5 Flash model for image analysis and data extraction.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
inputMethod
enum<string>
required

Indicates whether binary content is supplied via URL or base64-encoded string.

Available options:
url,
base64
images
string[]
required

Array of image URLs or base64-encoded strings to analyze.

Minimum length: 1
prompt
string
required

Instructions that describe the insights to extract from the images.

jsonMode
boolean
default:false

When true, requests the model to respond with JSON-formatted output.

requestSource
enum<string>

Optional identifier describing where the API request originated.

Available options:
API,
WEB,
MAKE_DOT_COM,
ZAPIER,
N8N,
PLAYGROUND,
DEFAULT_AUTOMATION,
AGENT_PREVIEW,
AGENT_LIVE,
AUTOPILOT,
STUDIO

Response

OCR results returned.

results
string
required

Model output returned from the extraction prompt.

prompt
string
required
imageCount
integer
required

Number of images processed.

creditUsage
integer
required

Credits consumed while processing the request.

I