Operations and retries
Inspect generation status, cancel work, and avoid duplicate submissions.
Speech and voice cloning create operations. Keep the server's X-Request-Id as soon as response headers arrive. For an accepted speech request or successful clone, this is the operation ID. Errors before an operation is created still have a tracing request ID, which may not identify an operation.
Inspect an operation
curl --fail --show-error "https://api.sawtakarabi.ai/v1/operations/$OPERATION_ID" \
-H "Authorization: Bearer $SAWTAK_API_KEY"The owning account can inspect its operation. The response includes:
| Field | Meaning |
|---|---|
id | Server operation ID. |
state | pending or terminal. |
outcome | null while pending; otherwise completed, stream_failed, cancelled, failed, or not_accepted. |
charged_micros | Charge in millionths of a US dollar. A pending operation's value is not a final charge. |
completion_bytes | Present for completed speech; delivered PCM audio bytes, excluding the header for WAV output. |
Use bounded polling when an operation is pending. Operation records are temporary: caller-supplied idempotency keys normally keep the record for 24 hours from creation; operations without a supplied key normally expire one hour after settlement. Cleanup can lag. This is not an audio archive or permanent billing history. A 404 can mean an expired, unknown, or other account's operation; it does not establish whether speech was generated or charged.
Cancel an operation
curl --fail --show-error -X POST \
"https://api.sawtakarabi.ai/v1/operations/$OPERATION_ID/cancel" \
-H "Authorization: Bearer $SAWTAK_API_KEY"Returns {"ok":true} after signaling cancellation of running work. It is not confirmation of a refund or terminal state. Inspect the operation again for the settled result. Cancellation after audio delivery may still be charged. A terminal operation is not restarted or refunded by this call.
Prevent duplicate submissions
Send a client-generated Idempotency-Key header for a speech or cloning request and keep it separately from the server operation ID. It must contain 1–128 UTF-8 bytes. Without this header, the gateway generates a new key for each request, so separate submissions are not recognized as duplicates.
For an existing pending, completed, or charged operation:
- Reusing the key returns HTTP
409witherror.code: duplicate_request, the originaloperation_id,state, andoutcome. It does not replay audio. - For speech, reusing the key with different request fields returns
409 idempotency_conflict. - Cloning deduplicates by key without comparing the uploaded body; use a new key for a deliberately new clone.
Keys are scoped to the account and operation type. They are not a permanent lock: a terminal operation that did not complete and was not charged releases its key for reuse, and expired records can be cleaned up. A retry can therefore start new work; do not treat submitting the same key as a read-only status check.
Interrupted speech
Save audio locally while streaming. Inspect status using the operation ID when available, preserve partial audio as incomplete, and ask before another paid generation. No endpoint retrieves missing audio from an interrupted API response. Neither a 200 response header nor a playable partial file proves completion. See Streaming audio and Generation records.
Operation inspection and cancellation require the owning account's key. Restricted credentials need tts for speech operations or voices for clones. They share a separate allowance of 600 requests per minute, with burst protection, so normal generation limits do not prevent cancellation.