API docs

Documentation

Generations

Start and track Raywake generations. Learn job statuses, safe polling, idempotent retries, stored outputs and signed download links.

Updated

Generations run asynchronously. Start one, then poll the job until it reaches a terminal status.

Statuses

Generation statuses
NameTypeDescription
queuedrunning
Accepted and waiting to start. Funds are held.
submittingrunning
Being handed to the model. Funds are held.
submittedrunning
The model is working. Funds are held.
finalizingrunning
The result is ready and being saved to storage. Funds are captured; outputs appear in a few seconds.
succeededterminal
Outputs are available. Funds were captured.
failedterminal
No result. Funds were released.
submission_unknownheld
Delivery could not be confirmed. Funds stay held until reconciled; this is not a refund. It can still turn succeeded or failed, so check again later (every few minutes).
needs_reviewheld
A result arrived but could not be read. Funds stay held until reviewed; the job then turns succeeded or failed.
needs_reconciliationheld
The job passed its settlement deadline. Funds stay held until reconciled; a late result can still turn it succeeded.

Polling

Poll GET /v1/jobs/{job_id} every 2–5 seconds. For short jobs you can instead pass ?wait=true to POST /v1/generate; the request then returns when the job is terminal or after about three minutes, whichever comes first.

Idempotency

Every generation requires an Idempotency-Key header. Retrying with the same key and the same body returns the original job instead of charging twice; the same key with a different body returns 409. Use a fresh UUID per intended generation.

How long are Raywake outputs and download links available?

Output files are stored for 30 days. Download URLs are signed for 7 days. While the file is still stored, request GET /v1/jobs/{job_id} again to obtain a fresh output link. Refreshing a link does not restart the file’s 30-day retention period. Download files you need to keep before they are deleted.

Use GET /v1/storage?kind=output to list stored output files; expires_at records each file’s deletion time. Both retrieval routes require jobs:read and return only files or jobs belonging to your account.

Next: Inputs and files →