One task ID connects the whole process
Creation returns HTTP 202. Save data.id, then use it for polling and every result download.
Create a dedicated key in the Developer Center and store it in an environment variable or secret manager.
Send a PDF or Office file as multipart form data with a target language and a unique Idempotency-Key.
Read the task every two to five seconds until its status becomes SUCCESS or FAILED.
After SUCCESS, call the download path with the same API key and save the returned document.
Create and secure an API key
Create a dedicated key in the Developer Center. The full secret is displayed only once.
- Store the key in an environment variable or secret manager, never in frontend JavaScript or a public repository.
- Choose a representative test file. For scans, tables, images, or dense formatting, start with a small but difficult sample.
- Generate one Idempotency-Key per business operation. Reuse it when a network timeout leaves the outcome unknown; after an explicit pre-task failure, fix the cause and use a new key. The maximum length is 128 characters.
Upload a PDF and create the task
Send multipart form data with the file, source language, and target language. This example translates a PDF to Chinese.
export FYPB_API_KEY="your_api_key"
curl -X POST \
'https://www.fanyipaiban.com/translate/openapi/v1/pdf/tasks' \
-H "Authorization: Bearer ${FYPB_API_KEY}" \
-H 'Idempotency-Key: quickstart-pdf-001' \
-F 'file=@./manual.pdf' \
-F 'source_lang=auto' \
-F 'target_lang=cn'Read the task ID from data.id
The response is wrapped in success, requestId, and data. Do not look for task_id; the current public field is data.id.
{
"success": true,
"requestId": "api-request-id",
"data": {
"id": "document-task-id",
"type": "PDF",
"billingUnit": "PER_PAGE",
"status": "QUEUED",
"progress": 0,
"billablePageCount": 12,
"pageTokenPrice": 1500,
"estimatedToken": 18000,
"chargedToken": null,
"downloadPath": "/openapi/v1/tasks/document-task-id/download",
"markdownDownloadPath": "/openapi/v1/tasks/document-task-id/download-markdown",
"comparisonDownloadPath": "/openapi/v1/tasks/document-task-id/download-comparison"
}
}Poll until SUCCESS or FAILED
Query the task every 2 to 5 seconds. QUEUED and RUNNING mean processing is still active; SUCCESS and FAILED are terminal states.
TASK_ID="document-task-id"
curl \
"https://www.fanyipaiban.com/translate/openapi/v1/tasks/${TASK_ID}" \
-H "Authorization: Bearer ${FYPB_API_KEY}"Download the result after SUCCESS
The main download endpoint returns the translated PDF or editable Office file. Calling it before SUCCESS returns 409 RESULT_NOT_READY.
curl -L \
"https://www.fanyipaiban.com/translate/openapi/v1/tasks/${TASK_ID}/download" \
-H "Authorization: Bearer ${FYPB_API_KEY}" \
-o translated-result.pdfA successful PDF task can expose three artifacts
/tasks/{id}/downloadThe primary translated and typeset result./tasks/{id}/download-markdownPDF only. Useful for retrieval, a knowledge base, or downstream processing./tasks/{id}/download-comparisonPDF only. Combines source and translation for review.Use the same flow for DOCX, PPTX, and XLSX
Only the creation endpoint changes. Polling and downloading continue to use the same task endpoints.
curl -X POST \
'https://www.fanyipaiban.com/translate/openapi/v1/office/tasks' \
-H "Authorization: Bearer ${FYPB_API_KEY}" \
-H 'Idempotency-Key: quickstart-office-001' \
-F 'file=@./product-spec.xlsx' \
-F 'source_lang=auto' \
-F 'target_lang=cn'Handle retries by error code, not by guesswork
Keep the requestId from error responses. It helps reconcile API logs with a failed integration attempt.
| HTTP | Typical code | What to do |
|---|---|---|
400 | MISSING_IDEMPOTENCY_KEY / INVALID_IDEMPOTENCY_KEY / MISSING_TARGET_LANGUAGE | Add or correct the required header or form field, then create a new request. |
401 | MISSING_API_KEY / INVALID_API_KEY | Check the Authorization header, Bearer token, and whether the key is active. |
402 | INSUFFICIENT_CREDITS | Recharge the shared balance, then create a new request with a new Idempotency-Key. |
409 | IDEMPOTENCY_KEY_IN_PROGRESS | Wait briefly, then retry the same create request with the same Idempotency-Key. |
409 | IDEMPOTENCY_KEY_REUSED | The earlier request failed before creating a task. Fix the cause, then use a new Idempotency-Key. |
409 | RESULT_NOT_READY | Keep polling the existing task and download only after status becomes SUCCESS. |
503 | PARSER_UNAVAILABLE | Retry later with a new Idempotency-Key because the earlier request returned an explicit failure. |
Know what counts as a billable page
PDF and Office translation currently use page-based billing at 1,500 credits per billable page. The API and web workspace share one balance.
Questions to settle before production use
Why is Idempotency-Key required?
An upload can time out after the server has already started creating a task. Reuse the same key when the outcome is unknown to prevent duplicate tasks and credit reservations. If the API explicitly reports a pre-task failure, fix the cause and use a new key.
Can I call the API directly from browser JavaScript?
Do not expose an API key in frontend code. Store the key on your server and call the document translation API from a backend service, worker, or controlled automation environment.
Should I batch-submit scanned PDFs immediately?
Test a representative sample first, especially a page with tables, images, headers, or dense formatting. Recognition quality and layout complexity affect the review and delivery workflow.
Does the API use a separate credits balance?
No. The API, MCP integration, and web workspace use the same credits balance, so you can test a file in the workspace before automating the confirmed workflow.
Start with one representative document
Run upload, polling, and download end to end. Review the result and chargedToken before connecting a batch or production workflow.