Generation status, polling, and results
Poll Rivya generation tasks by public task ID. Read task states, result URLs when available, credit settlement, and request errors.
Last reviewed on November 11, 2026
Use GET /api/v1/generations/{taskId} to check an asynchronous generation job. Use the public task id returned when you create a generation, not the model provider's task ID.
This endpoint checks an existing Rivya task instead of creating a new Rivya task record. Chat requests use separate endpoints and session records. See Chat API for chat results and streams.
Prompt units and complete layer results
Read prompt_length_unit together with max_prompt_length from GET /api/v1/models. utf8_bytes counts the original text bytes, including spaces and line breaks; utf16_code_units counts JavaScript UTF-16 units. A null limit does not mean unlimited or optional text. Gemini TTS uses the byte unit.
A completed layer-decomposition result can include result.layers alongside the complete result.urls list. Keep each layer’s z_index, URL, size, name, description and bounding box when provided; index zero is the base image. The TypeScript SDK exposes these fields. Upload references for the selected model and pass its original signed metadata; declared dimensions or duration alone do not replace verification.
Endpoint
The endpoint and header examples below show the request format; they are not shell commands. Replace {taskId} with your public task ID.
GET https://rivya.ai/api/v1/generations/{taskId}Send the full API key in this header. The key needs generations:read, and authenticated Public API access must be enabled:
Authorization: Bearer rvya_sk_...Use your key only in server-side requests over HTTPS. See API key authentication for key creation, permissions, and expiry.
curl example
Replace task_public_id and rvya_sk_... with your task ID and API key before running this request. Keep the real key out of public code, logs, and shared examples.
curl https://rivya.ai/api/v1/generations/task_public_id \
-H "Authorization: Bearer rvya_sk_..."Status values
Read the task's status field in a successful response:
queued: Rivya has a task record, but no final result or failure has been recorded. This is not a queue position.processing: the task is still in progress. This can include time in the model service's queue.succeeded: Rivya has recorded a successful result. Media URLs and credit settlement must be checked separately.failed: Rivya has recorded a task failure. Read itserrorobject and check the credit settlement.
queued and processing do not give a completion estimate. succeeded and failed are final generation states, but a successful task can still need credit reconciliation.
Succeeded response
This example shows a successful task with a media URL and completed credit settlement. The model, credit amounts, timestamps, and media URL are illustrative; they are not a current price quote, a completion-time promise, or a real output to download.
{
"id": "task_public_id",
"status": "succeeded",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 1,
"settlement_status": "SETTLED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:01:00.000Z",
"result": {
"primary_url": "https://media.example/result.png",
"urls": ["https://media.example/result.png"]
},
"error": null
}For a succeeded task, result is an object. primary_url is the first recorded media URL when present; it can be null. urls contains the recorded URL list and can be empty. Do not assume that succeeded always supplies a downloadable file.
Some tasks return text rather than media. This endpoint exposes the result URLs, not the full text result. A missing URL does not by itself mean the generation failed.
For other task states, result is null. created_at is the task's creation time, and updated_at is the task record's last update; neither is an estimated finish time.
Failed response
This example shows a confirmed failure whose reserved credits were returned. The error code and message are examples; read the values returned for your task.
{
"id": "task_public_id",
"status": "failed",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 0,
"settlement_status": "REFUNDED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:01:00.000Z",
"result": null,
"error": {
"code": "generation_failed",
"message": "The generation failed."
}
}A task with status: failed has an error object with code and message. Other task states have error: null. This task error is separate from an HTTP error returned when the status request itself cannot be completed.
A failed task does not always mean credits were deducted and then returned. For example, a request rejected for insufficient credits has no successful deduction to refund. Check settlement_status and the account's credit transactions.
Credit settlement
API generation and Studio use the same account credit wallet. Rivya normally deducts the reserved amount before submitting a billable generation. Refreshing a task's status can also update its credit settlement.
reserved_credits: the amount reserved for the task, not a universal model price.final_credits: the amount currently recorded for the task. It can equal the reservation before settlement is complete; do not treat it as final without checkingsettlement_status.settlement_status: the separate credit-settlement state. Its values arePENDING,RESERVED,SETTLED,REFUNDED,FAILED, andRECONCILIATION_REQUIRED.
New generation tasks normally start with RESERVED; PENDING also indicates that final settlement has not been recorded. With SETTLED, successful usage has been settled. If valid final usage is lower than the reservation, the difference is returned to the account.
RECONCILIATION_REQUIRED means settlement is still unresolved. This can occur when final usage is missing, invalid, or greater than the reservation. The reserved amount remains recorded while Rivya reconciles the usage; it does not automatically deduct the excess. A later status check can show an updated settlement.
REFUNDED means the reserved credits were returned to the account. A settlement status of FAILED means no refund was recorded for the task. This value is separate from task status: failed; it does not by itself prove that credits were deducted.
A long wait, unchanged status, or query error is not a confirmed generation failure and does not establish a refund. Returned Rivya credits go to the account balance, not a payment card. See API Credits and Failed tasks and credit returns for balance checks and troubleshooting.
Polling guidance
Keep the original task ID and leave a delay between status requests. Avoid tight loops.
One possible starting pattern is:
Wait 2–3 seconds after submission before the first status check.
While the task is
queuedorprocessing, poll about every 5–10 seconds and increase the interval if it remains pending.Use longer intervals for long-running video or audio jobs, and add jitter when many clients poll at once.
Stop polling for generation progress after
succeededorfailed. If a successful task still hasRECONCILIATION_REQUIRED, check settlement again later with backoff.
These intervals are client-side suggestions, not a completion estimate or a promise that each request will query the model service. Set a limit on how long your client waits. Reaching that limit does not cancel the task or prove it failed.
Saved status and query errors
Rivya attempts to refresh eligible tasks, but a response can contain the last saved status. For example, frequent checks can fall within the refresh interval, or the model service may not return a usable update. A successful HTTP response does not guarantee a fresh provider query.
If the status request returns an HTTP error or the connection fails, you have not received a new task status. Keep the last known state and retry the same status endpoint when appropriate. Do not change the task to failed in your application or submit another generation solely because this query failed.
For request errors, follow API errors, rate limits, and retries. Keep the task ID and any returned requestId for troubleshooting; do not share your API key.
Ownership boundary
The task must belong to the Rivya account that owns the API key. If the task does not exist or belongs to another account, the endpoint returns not_found with HTTP 404.
Ownership is checked by account, not by the particular key that submitted the task. Another valid key for that account can read it if the key has generations:read and API access is enabled. A model's presence in the public catalog does not grant task access.
