API reference
Tasks
Submit, fetch and list tasks, download results, and avoid duplicate submissions.
Every generation is an asynchronous task: submit it, get its ID at once, then poll for the result or wait for a callback.
Submit a task
POST /v1/tasks
Body fields:
model(required): the model ID. See the model list orGET /v1/models.input(required): generation parameters, which depend on the model's media type. See Models and parameters.route(optional): which routes this request may use, in what order. See Routes and routing.callback_url(optional): an https URL we post the result to when the task ends. See Callbacks.upload(optional): presigned upload URLs, one per output file, to put the files straight into your own storage. See Upload to your storage.
curl https://api.janvia.io/v1/tasks \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-123" \
-d '{
"model": "gpt-image-2",
"input": { "prompt": "a red fox in the snow", "resolution": "2K" },
"route": ["fast", "cheap"]
}'Success is HTTP 202 with the task object; the Location header is the task's URL. Errors at submit time (bad parameters, low balance and so on) return a 4xx, create no task and charge nothing.
The task object
{
"id": "task_9f2c...",
"object": "task",
"model": "gpt-image-2",
"media_type": "image",
"status": "completed",
"progress": 100,
"input": { "prompt": "a red fox in the snow", "resolution": "2K" },
"route": "fast",
"route_name": "Fast",
"routing": {
"routes": [
{ "id": "fast", "name": "Fast", "price_usd": 0.06 },
{ "id": "cheap", "name": "Cheap", "price_usd": 0.04 }
],
"source": "request",
"rule": null
},
"output": {
"files": [
{
"type": "image",
"url": "https://...",
"mime_type": "image/png",
"width": 2048,
"height": 2048
}
]
},
"error": null,
"cost_usd": 0.06,
"quote_usd": 0.06,
"usage": null,
"callback": null,
"upload": null,
"created_at": "2026-10-21T08:00:00.000Z",
"finished_at": "2026-10-21T08:00:12.000Z"
}status:queued,in_progress,completedorfailed. Withupload, a task staysin_progressuntil its files are uploaded.progress: 0–100; it moves only when the upstream reports progress.route/route_name: the route serving (or that served) the task.routing.routes: the routes this task may use, in the order they are tried, with their prices.sourcesays where the list came from:request(the request'sroute),rule(an exception rule on the key;ruleis its 0-based index),key(the key's sort settings) ordefault(cheapest first).output.files: the generated files.typeisimage,videooraudio; images havewidthandheight, video and audio may havedurationin seconds.error: on failure, acodeandmessage(plus acategoryfor content refusals). See Errors.cost_usd: what the task cost; 0 when it failed (refunded). A route priced per token settles on the tokens used when the task completes, so this can differ fromquote_usd.quote_usd: the estimate charged at submit.usage: on routes priced per token, the tokens the upstream reported once the task completes:input_text_tokens,input_image_tokens,output_tokens;nullelsewhere. See Billing.callback: with acallback_url, how its delivery went; otherwisenull. See Callbacks.upload: withupload, how the files went to your storage; otherwisenull. See Upload to your storage.- base64 images in
inputare shown shortened.
Fetch a task
curl https://api.janvia.io/v1/tasks/TASK_ID \ -H "Authorization: Bearer $API_KEY"
Polling every 3–5 seconds is plenty; video can wait longer. You can only fetch your own account's tasks; anything else returns 404 task_not_found.
List tasks
GET /v1/tasks returns your tasks, newest first. Every query parameter is optional:
limit: how many to return, 1–100, 20 by default.status: only tasks in this status:queued,in_progress,completedorfailed.model: only tasks for this model.after: the ID of the last task in the previous answer; the list continues after it.
curl "https://api.janvia.io/v1/tasks?status=completed&limit=50" \ -H "Authorization: Bearer $API_KEY"
{ "object": "list", "data": [ ... ], "page": 1, "limit": 50, "total": 132, "has_more": true }When has_more is true, there are older tasks: ask again with the ID of the last task in data as after, until has_more is false. This walks every task once, even while new ones are submitted. An answer to after has only object, data, limit and has_more.
You can also ask for a page (from 1), which comes with the total. But pages shift when new tasks arrive, so a later page can repeat a few tasks from an earlier one; use after to go through all of them.
Download results
output.files[].url is either a CDN URL or this site's /v1/tasks/TASK_ID/content/N. Both download without a key: task IDs are random and can't be guessed, so don't share these URLs publicly.
Files we store are kept for 24 hours after the task completes, then deleted: their URLs stop working, and /v1/tasks/TASK_ID/content/N returns 410. Download them within 24 hours, or pass upload to have us upload them to your storage, where this limit doesn't apply.
Avoid duplicate submissions
Retrying after a network timeout could submit (and pay for) the same task twice. Send an Idempotency-Key header (1–128 letters, digits or _ . : -) to prevent it:
- Within 24 hours, the same key with the same body returns the same task (HTTP 200 with
Idempotency-Replayed: true) and charges nothing more. - The same key with a different body returns 409
idempotency_conflict.