API Examples

Version

API

Route

POST PUT POST

/api/v2/api/translate/uploads
R2 target
/api/v2/api/translate

Parameters

Parameter	Required	Type	Description
`image`	Yes	file[]	One or more image files, or one ZIP archive
`source_language`	No	string	Optional; required when model is manga (e.g., ja)
`target_language`	Yes	string	Target language code (e.g., en)
`model`	No	string	Model; omit to use the API default
`font`	No	string	Font; legacy font_style is also accepted

Parameter	Required	Type	Description
`Idempotency-Key`	Yes	HTTP header	Prepare request header: stable key used to safely retry the same file manifest for 8 hours
`platform`	No	string \| null	Prepare and final requests: optional self-reported platform label used only for API call auditing
`files[]`	Yes	array<object>	Prepare request: file metadata containing filename, content_type, size, and content_sha256
`upload_id`	Yes	string	Final request: opaque upload batch ID returned by prepare
`files[].index files[].upload_intent`	Yes	integer string	Final request: per-file index and opaque upload_intent returned by prepare; send only after each R2 upload finishes
`source_language`	No	string	Optional; required when model is manga (e.g., ja)
`target_language`	Yes	string	Target language code (e.g., en)
`model`	No	string	Model; omit to use the API default
`font`	No	string	Font; legacy font_style is also accepted

Parameter	Required	Type	Description
`batch_id`	Yes	string	Batch identifier used to query task status

Parameter	Required	Type	Description
No parameters

Response Params

Field	Type	Description
`task_id`	string	Task identifier
`batch_id`	string	Batch identifier used to query task status

Field	Type	Description
`status`	integer	Application status code; 200 on success
`cost_ms`	integer	Time spent handling this API request in milliseconds
`request_id`	string	Request identifier for tracing this API call
`data`	object	Translation task identifiers returned after the request is accepted
`message`	string	Always success for a successful API response; it does not mean the translation task has completed
`data.task_id`	string	Task identifier
`data.batch_id`	string	Batch identifier used to query task status

Field	Type	Description
`status_code`	integer	Always 200 for a successful Task Status response
`request_id`	string	Request identifier for tracing this API call
`auth_type`	string	Always account for a PAT-authenticated Task Status request
`task_reference`	string	The batch_id from the request path, returned unchanged
`data`	object	Container for per-image results and the overall task status
`data.items`	array<object>	Array of per-image task results
`data.items[].image_id`	string	Stable identifier for the image result
`data.items[].index`	integer	Zero-based position of the image in the batch
`data.items[].filename`	string	Original image filename
`data.items[].status`	string	Image result status (pending \| processing \| completed \| failed \| canceled)
`data.items[].original_url`	string	Source image URL. It is available for current API-created tasks.
`data.items[].translated_url`	string	Translated image URL; an empty string until a translated result is available, including for pending, processing, or failed images.
`data.items[].is_translated`	boolean	True only when a completed translated image URL is available
`data.items[].output_file_path`	string	Compatibility alias of translated_url; an empty string when no translated image is available.
`data.items[].message`	string \| null	Optional info message
`data.items[].error`	string \| null	Error detail when the image task fails; null otherwise
`data.items[].inpaint_image_url`	string \| null	Erased-text image URL, or null when the selected model or execution path does not generate one.
`data.items[].block_json`	array<object>	Structured text block data retained by V1; may be an empty array when the selected model or execution path does not return block metadata.
`data.task_status`	string	Overall task status (pending \| processing \| completed \| failed \| canceled)

Field	Type	Description
`status`	integer	Application status code; 200 on success
`cost_ms`	integer	Task elapsed time in milliseconds; 0 when valid task timestamps are unavailable
`request_id`	string	Request identifier for tracing this API call
`data`	array<object>	Array of compact per-image results
`message`	string	Always success for a successful API response; it does not mean the translation task has completed
`data[].image_id`	string	Stable identifier for the image result
`data[].filename`	string	Original image filename
`data[].status`	string	Image result status (pending \| processing \| completed \| failed \| canceled)
`data[].original_url`	string	Source image URL. It is available for current API-created tasks.
`data[].translated_url`	string	Translated image URL; an empty string until a translated result is available, including for pending, processing, or failed images.
`data[].erased_url`	string	Erased-text image URL; may be an empty string. Models or execution paths that return only a finished image, such as Manga with the Auto finished-image path, do not generate it.
`data[].blocks`	array<object>	Structured translated text blocks; may be an empty array when the selected model or execution path does not return block metadata, such as Manga with the Auto finished-image path.
`data[].blocks[].angle`	number	Rotation angle of the text block
`data[].blocks[].color`	string	Hex color used for the translated text
`data[].blocks[].handwritten`	boolean	Whether the source text was detected as handwritten
`data[].blocks[].location`	object	Four-corner bounds of the text block
`data[].blocks[].location.left_bottom`	array<number>	Coordinate pair for the named corner
`data[].blocks[].location.right_bottom`	array<number>	Coordinate pair for the named corner
`data[].blocks[].location.left_top`	array<number>	Coordinate pair for the named corner
`data[].blocks[].location.right_top`	array<number>	Coordinate pair for the named corner
`data[].blocks[].text`	string	Translated text rendered for the block
`data[].blocks[].direction`	string	Writing direction of the translated text

Field	Type	Description
`subscription_credits`	integer	Credit balance for the named category
`subscription_credits_expires_at`	string \| null	Subscription credit expiration time in ISO 8601 format, or null
`one_time_credits`	integer	Credit balance for the named category
`one_time_credits_expires_at`	string \| null	One-time credit expiration time in ISO 8601 format, or null
`free_credits`	integer	Credit balance for the named category
`total_credits`	integer	Sum of all available credit balances
`is_temporary`	boolean	Whether the balance belongs to a temporary account

Field	Type	Description
`status`	integer	Application status code; 200 on success
`cost_ms`	integer	Time spent handling this API request in milliseconds
`request_id`	string	Request identifier for tracing this API call
`data`	object	Container for the current credit balances
`message`	string	Always success for a successful API response; it does not mean the translation task has completed
`data.total_credits`	integer	Sum of all available credit balances
`data.is_temporary`	boolean	Whether the balance belongs to a temporary account
`data.detail`	object	Breakdown of available credits by category
`data.detail.subscription`	object	Credit balance and expiration for the named category
`data.detail.subscription.credits`	integer	Credit balance for the named category
`data.detail.subscription.expires_at`	string \| null	Credit expiration time in ISO 8601 format, or null
`data.detail.one_time`	object	Credit balance and expiration for the named category
`data.detail.one_time.credits`	integer	Credit balance for the named category
`data.detail.one_time.expires_at`	string \| null	Credit expiration time in ISO 8601 format, or null
`data.detail.free`	object	Credit balance and expiration for the named category
`data.detail.free.credits`	integer	Credit balance for the named category
`data.detail.free.expires_at`	null	Always null because this aggregate endpoint does not provide a single expiration time for free credits

Sample Response (JSON)

{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "batch_id": "00000000-0000-4000-8000-000000000001"
}

Sample Response (JSON)

{
  "status": 200,
  "cost_ms": 125,
  "request_id": "4b7370383cacccc7",
  "data": {
    "task_id": "00000000-0000-4000-8000-000000000001",
    "batch_id": "00000000-0000-4000-8000-000000000001"
  },
  "message": "success"
}

Sample Response (JSON)

{
  "status_code": 200,
  "request_id": "4b7370383cacccc7",
  "auth_type": "account",
  "task_reference": "00000000-0000-4000-8000-000000000001",
  "data": {
    "items": [
      {
        "image_id": "00000000-0000-4000-8000-000000000001_0",
        "index": 0,
        "filename": "007.jpg",
        "status": "completed",
        "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
        "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "is_translated": true,
        "output_file_path": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
        "message": "ok",
        "error": null,
        "inpaint_image_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
        "block_json": []
      }
    ],
    "task_status": "completed"
  }
}

Sample Response (JSON)

{
  "status": 200,
  "cost_ms": 5300,
  "request_id": "4b7370383cacccc7",
  "data": [
    {
      "image_id": "00000000-0000-4000-8000-000000000001_0",
      "filename": "007.jpg",
      "status": "completed",
      "original_url": "https://storage.example.com/manga-demo/input/00000000-0000-4000-8000-000000000001/007.jpg",
      "translated_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007.jpg",
      "erased_url": "https://storage.example.com/manga-demo/output/00000000-0000-4000-8000-000000000001/007-erased.jpg",
      "blocks": [
        {
          "angle": 0,
          "color": "#484848",
          "handwritten": false,
          "location": {
            "left_bottom": [1685, 293],
            "right_bottom": [1786, 293],
            "left_top": [1685, 264],
            "right_top": [1786, 264]
          },
          "text": "OOOUGH!",
          "direction": "horizontal"
        }
      ]
    }
  ],
  "message": "success"
}

Sample Response (JSON)

{
  "subscription_credits": 0,
  "subscription_credits_expires_at": null,
  "one_time_credits": 0,
  "one_time_credits_expires_at": null,
  "free_credits": 10,
  "total_credits": 10,
  "is_temporary": true
}

Sample Response (JSON)

{
  "status": 200,
  "cost_ms": 4,
  "request_id": "4b7370383cacccc7",
  "data": {
    "total_credits": 10,
    "is_temporary": true,
    "detail": {
      "subscription": {
        "credits": 0,
        "expires_at": null
      },
      "one_time": {
        "credits": 0,
        "expires_at": null
      },
      "free": {
        "credits": 10,
        "expires_at": null
      }
    }
  },
  "message": "success"
}

Error Response Params

On V2 failures, the HTTP status is preserved and the same five-field envelope is returned.

Field	Type	Description
`status`	integer	Actual HTTP error status code
`cost_ms`	integer	Time spent handling this API request in milliseconds
`request_id`	string	Request identifier for tracing this API call
`data`	object	Error-data container containing only the stable machine-readable code
`message`	string	Public error message; internal diagnostic details are not exposed
`data.code`	string	Stable machine-readable error code

Error Response Example (JSON)

{
  "status": 400,
  "cost_ms": 1,
  "request_id": "4b7370383cacccc7",
  "data": {
    "code": "PZ_API_ACCESS_BAD_REQUEST"
  },
  "message": "Invalid target language"
}

Example Inputs

API Key

Source language

Target language

Model

Font

API Examples

Route

Parameters

Response Params

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Error Response Params

Error Response Example (JSON)

Example Inputs

Python3 Example

cURL Examples

Python3 Example

cURL

Python3 Example

cURL

Route

Parameters

Response Params

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Sample Response (JSON)

Error Response Params

Error Response Example (JSON)

Example Inputs

Python3 Example

cURL Examples

Python3 Example

cURL

Python3 Example

cURL

Cookie Preferences