Async jobs

The async twin of every verb. Send the body you would send to the ordinary verb to /v1/async/<verb>; you get a 202 with a job id at once, and the job runs in the background through the same path, the same rules and the same bill. For video, image or speech generation that takes minutes, or whenever you would rather not hold a connection open.

curl https://iranrouter.com/v1/async/videos \
  -H "Authorization: Bearer ir-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "alibaba/wan-3.0", "prompt": "یک گربه روی دوچرخه", "duration": 5}'

{
  "id": "3f6c...-job-id",
  "object": "async.job",
  "verb": "videos",
  "status": "queued",
  "created_at": "2026-09-16T10:00:00.000Z",
  "poll_url": "/v1/async/videos/3f6c...-job-id"
}

The job: queued, running, completed or failed. When completed, result is exactly the body the ordinary verb returns (with usage.cost_rial); a binary answer (audio/speech) carries a content_url instead. When failed, error is the ordinary verb's error envelope and http_status its code — a 402 for balance or a 429 for rate shows up right there.

curl https://iranrouter.com/v1/async/videos/3f6c...-job-id -H "Authorization: Bearer ir-..."

{
  "id": "3f6c...-job-id",
  "object": "async.job",
  "verb": "videos",
  "status": "completed",
  "http_status": 200,
  "result": { "id": "…", "object": "video.job", "status": "completed", "content_url": "/v1/videos/…/content", "usage": { "cost_rial": 1250000 } }
}

• stream is always off: the result is stored whole.
• Up to 20 open jobs per user and 600 an hour; past that, 429 with code async_limit_reached or async_rate_reached.
• Results are kept for 24 hours. Poll every few seconds; video usually takes a few minutes.
• Multipart uploads (audio/transcriptions, translations) have no async twin.
• Idempotency-Key works here exactly as it does on chat/completions and the unary verbs.