Async Jobs

Long-running work uses the async job model: you submit the request and collect the result later. The gateway has two kinds, and their polling paths differ.

1. Responses background jobs

Pass background: true to POST /v1/responses and it responds immediately with status: "queued".

{
  "model": "everyais/claude-opus-5",
  "input": "A long research task...",
  "background": true
}

• Polling: GET /v1/responses/{id}
• State transitions: queued → in_progress → completed / incomplete / failed / cancelled
• Cancel: POST /v1/responses/{id}/cancel (only queued and in_progress can be cancelled, and the reserved credit is refunded)

2. Video generation jobs

POST /v1/videos/generations is always async. Poll with the id from the response.

• Polling: GET /v1/videos/generations/{id}
• While in progress you get Retry-After: 5 — poll at 5-second intervals.
• Status: processing / completed / failed / cancelled

⚠️ Looking up a video job via GET /v1/outputs/{requestId} returns 404. The two ids live in different spaces, and /v1/outputs is for browsing the history of completed requests.

3. Webhooks instead of polling

To be notified on completion without polling, register a webhook endpoint in the dashboard and subscribe to the video.completed and video.failed events.

The video.completed payload carries jobId, model, status, durationSeconds, cost, and data.

The other subscribable events are credit.low, credit.depleted, credit.recharged, credit.recharge_failed, cost.threshold, cost.limit_hit, payment.succeeded, payment.failed, anomaly.detected, and key.expiring.