API Reference

Jobs API

POST /v1/jobs queues an operation. GET /v1/jobs/{id} checks status, progress, and debited credits.

Queue a Job (POST /v1/jobs)

The request must include an Idempotency-Key header. Replaying the same key with identical input returns the original job without creating duplicates.

operationstringrequired

Studio operation name: 'document.translate', 'document.extract', 'document.transliterate', 'document.summarize', 'audio.transcribe', 'document.narrate', 'audio.dub', or 'music.generate'.

inputobjectrequired

Operation-specific payload containing uploadId and tool parameters.

webhookUrlstringoptional

Optional HTTPS URL to receive an HMAC-signed JSON payload upon job state transitions.

Public Job Object

FieldTypeDescription
idstringUnique public UUID for the job
operationstringThe operation that was called
statusstringqueued | running | succeeded | failed
createdAtstringISO 8601 UTC timestamp
errorCodestring | nullError identifier if the job failed
chargedCreditsnumber | nullExact number of credits debited upon completion
resultobject | nullOnly on GET /v1/jobs/{id}. null until the job succeeds. See Getting the result below.

Getting the result

When status is succeeded, GET /v1/jobs/{id} includes a result. For document.translate, document.transliterate and document.extract it is a file: { type: "file", fileName, url, expiresAt }. url is a signed download link valid for one hour; fetch the job again for a fresh link. For document.summarize it is { type: "summary", text, pages }. Audio operations return { type: "files", text, files: [{ role, fileName, url, expiresAt }] }, one entry per output file. GET /v1/jobs (the list) does not include result.

Download a translated file
curl -s https://api.transpera.io/v1/jobs/JOB_ID \
  -H "Authorization: Bearer tp_live_YOUR_KEY"

# {"job": {"id": "...", "status": "succeeded", "chargedCredits": 90,
#   "result": {"type": "file", "fileName": "report_hi.docx",
#     "url": "https://storage.googleapis.com/...", "expiresAt": "2026-11-19T14:00:00.000Z"}}}

curl -o translated.docx "SIGNED_URL_FROM_RESULT"