Image Converter API Documentation¶

Overview¶

The Image Converter API allows developers to convert images between multiple formats, including Base64 encoding and decoding. It supports both synchronous (direct body upload) and asynchronous (remote URL or uploaded file) operations.

This tool can:

Convert between image formats (jpg, jpeg, png, gif, webp)
Encode images to Base64 text
Decode Base64 text to image files

Base URL:
https://api.apidatatools.com/image-converter-api

Endpoint (POST)¶

POST https://api.apidatatools.com/image-converter-api

Headers¶

Header	Type	Required	Description
`x-source-format`	string	Yes	Source format of the input (`jpg`, `jpeg`, `png`, `gif`, `webp`, `base64`)
`x-destination-format`	string	Yes	Desired output format (`jpg`, `jpeg`, `png`, `gif`, `webp`, `base64`)
`x-source-type`	string	Optional	Defines input source: `body`, `url`, or `file`. Default is `body`.
`x-api-key`	string	Yes	Authentication Key `abcd1234xyz`

Accepted File Extensions¶

Mode	Supported Extensions
Body / File / URL	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.txt`

Input Example (Body Mode)¶

Headers:

x-source-format: jpg
x-destination-format: png
x-source-type: body
x-api-key: YOUR_API_KEY

Body:
Binary image

Input Example (URL Mode)¶

Headers:

x-source-format: jpg
x-destination-format: base64
x-source-type: url

Body:

{
  "url": "https://example.com/sample.jpg"
}

Input Example (File Mode)¶

Headers:

x-source-format: png
x-destination-format: jpg
x-source-type: file

Body:

{
  "file": "user_uploads/abc123/sample.png"
}

Example Request¶

Synchronous (Body Input)¶

curl -X POST "https://api.apidatatools.com/image-converter-api" \
  -H "x-source-format: jpg" \
  -H "x-destination-format: png" \
  -H "x-source-type: body" \
  --data-binary "@sample.jpg"

Asynchronous (Remote File URL)¶

curl -X POST "https://api.apidatatools.com/image-converter-api" \
  -H "x-source-format: jpg" \
  -H "x-destination-format: base64" \
  -H "x-source-type: url" \
  -d '{"url": "https://example.com/sample.jpg"}'

Asynchronous (Input File)¶

curl -X POST "https://api.apidatatools.com/image-converter-api" \
  -H "x-source-format: png" \
  -H "x-destination-format: webp" \
  -H "x-source-type: file" \
  -d '{"file": "user_uploads/abc123/sample.png"}'

Example Response¶

Successful (Body Mode)¶

{
  "status": "success",
  "request_id": "b7e2f9d1-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.png",
  "preview": "Conversion Successful."
}

Async Job Accepted¶

{
  "status": "accepted",
  "job_id": "job-12345-abcde",
  "status_url": "https://api.apidatatools.com/jobs/job-12345-abcde",
  "request_id": "b7e2f9d1-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Error Handling¶

Error Code	HTTP Status	Description	Example
`MISSING_FORMATS`	400	Missing `x-source-format` or `x-destination-format` headers	`{"status":"error","error":"MISSING_FORMATS","details":{"message":"Both x-source-format and x-destination-format headers are required."}}`
`UNSUPPORTED_FORMAT`	400	Unsupported image format	`{"status":"error","error":"UNSUPPORTED_FORMAT","details":{"message":"Supported formats: base64, gif, jpeg, jpg, png, webp"}}`
`INVALID_INPUT_TYPE`	400	Input is not bytes	`{"status":"error","error":"INVALID_INPUT_TYPE","details":{"message":"Image input must be bytes."}}`
`INVALID_BASE64`	400	Invalid Base64 input	`{"status":"error","error":"INVALID_BASE64","details":{"message":"Invalid base64 image input."}}`
`EMPTY_IMAGE`	400	Empty image input	`{"status":"error","error":"EMPTY_IMAGE","details":{"message":"Image input is empty."}}`
`INVALID_IMAGE_FILE`	400	Failed to decode image	`{"status":"error","error":"INVALID_IMAGE_FILE","details":{"message":"Failed to decode input image."}}`
`IMAGE_CONVERSION_FAILED`	400	Conversion failed	`{"status":"error","error":"IMAGE_CONVERSION_FAILED","details":{"message":"Failed to convert image."}}`
`FILE_TOO_LARGE`	413	File exceeds plan limit	`{"status":"error","error":"FILE_TOO_LARGE","details":{"message":"Remote file exceeds plan limit."}}`
`INVALID_URL`	400	Invalid or missing URL	`{"status":"error","error":"INVALID_URL","details":{"message":"Missing or invalid 'url'."}}`
`URL_UNREACHABLE`	400	URL not reachable	`{"status":"error","error":"URL_UNREACHABLE","details":{"message":"Could not reach URL"}}`
`URL_NOT_OK`	400	URL returned non-200 status	`{"status":"error","error":"URL_NOT_OK","details":{"message":"URL returned HTTP 404, expected 200."}}`
`INVALID_FILE`	400	Invalid file reference	`{"status":"error","error":"INVALID_FILE","details":{"message":"Missing or invalid 'file'."}}`
`INVALID_FILE_EXTENSION`	400	Unsupported file extension	`{"status":"error","error":"INVALID_FILE_EXTENSION","details":{"message":"Invalid or unsupported file extension"}}`
`FILE_UNAVAILABLE`	400	File not accessible	`{"status":"error","error":"FILE_UNAVAILABLE","details":{"message":"Could not access file"}}`
`PAYLOAD_TOO_LARGE`	413	Request body exceeds plan limit	`{"status":"error","error":"PAYLOAD_TOO_LARGE","details":{"message":"Request body exceeds limit"}}`
`INTERNAL_ERROR`	500	Unexpected internal error	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process your request"}}`

Async Job Status¶

Endpoint:
GET https://api.apidatatools.com/jobs/{job_id}

Example Status Response for Async¶

Queued¶

{
  "job_id": "job-12345-abcde",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Success¶

{
  "job_id": "job-12345-abcde",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345690,
  "result": {
    "status": "success",
    "request_id": "b7e2f9d1-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.webp",
    "preview": "Conversion Successful."
  }
}

Failed¶

{
  "job_id": "job-12345-abcde",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345680,
  "error": {
    "code": "IMAGE_CONVERSION_FAILED",
    "message": "Failed to convert image.",
    "details": {
      "message": "Failed to convert image."
    }
  }
}

Notes for Developers¶

The API supports three input modes: body, url, and file.
For asynchronous operations, a job_id and status_url are returned. Use the Status API to poll job progress.
The output file is stored temporarily and accessible via a secure download link.
Always include both x-source-format and x-destination-format headers.
Base64 conversions return a .txt file containing the encoded string.
For image-to-image conversions, the output file type matches the destination format.
Each response includes a unique request_id for tracking and debugging.
Ensure your plan limits allow for the file size being processed.