Jobs

Animated exports use a persisted queue. Synchronous generation remains available for existing clients.

Create an export

POST /v1/jobs
Authorization: Bearer YOUR_KEY
Content-Type: application/json

{
  "generator": "shader-gradient",
  "params": { "loopSeconds": 6 },
  "seed": 42,
  "format": "mp4",
  "size": { "width": 640, "height": 360, "pixelRatio": 1 }
}

The response is 202 with an ID, status, progress and timestamps. The legacy slug field is also accepted. The default format for jobs is GIF.

Monitor progress

GET /v1/jobs lists your export history. GET /v1/jobs/{id} returns one job.

Statuses are queued, running, completed, failed and cancelled. Progress ranges from 0 to 1. Responses include attempts, resultReady, cancelled, optional error, contentType and resultUrl.

Cancel and retry

POST /v1/jobs/{id}/cancel cancels queued or running work and stops its renderer. Cancelling a completed or failed job returns 409 job_finished.

Retry a failed or cancelled export by creating another job with the same request. Editor exports include a Retry control.

Download results

GET /v1/jobs/{id}/result returns the completed file. An unfinished result returns 409 not_ready. A completed job whose file is missing returns 410 result_missing; its metadata also reports the missing result.

Duration and limits

Loops render at 24 fps for the requested loopSeconds. Shader Gradient supports 1–30 seconds; other animated generators expose their limits in discovery. There is no four-second truncation.

The queue runs two jobs concurrently, with a default whole-operation timeout of 10 minutes. Configure JOB_TIMEOUT_MS when necessary. At most 20 unfinished jobs per workspace and 50 globally are accepted. Encoded output is limited to 48 MB.

Restart recovery

Queue state, owner, progress and result locations are stored in SQLite. Unfinished work is retried after startup, up to three attempts. Successful usage is recorded transactionally once, including across restarts. Completed jobs remain downloadable until their result file is removed.