Jobs
Jobs and polling
Every generate call creates a job. Store its id the moment the submit returns: it is the key for status, result, cancel and webhooks.
States
| sume_status | status | Terminal | Meaning |
|---|---|---|---|
queued | IN_QUEUE | No | Accepted, waiting for a worker. |
processing | IN_PROGRESS | No | The model is running. |
completed | COMPLETED | Yes | result.artifacts holds the output. |
failed | FAILED | Yes | error says why. The price is refunded. |
canceled | CANCELED | Yes | Canceled before generation started. Refunded. |
Both spellings always agree. next_action tells you what to do: poll_status, fetch_result, or inspect_events when a job ended without a result.
Get status
GEThttps://api.sume.com/v1/jobs/{id}/status
{
"data": {
"request_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"job_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"status": "IN_PROGRESS",
"sume_status": "processing",
"status_url": "https://api.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
"result_url": "https://api.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
"cancel_url": null,
"cancelable": false,
"next_action": "poll_status",
"next_poll_after_seconds": 2,
"result_ready": false,
"terminal": false
}
}Polling
Wait next_poll_after_seconds between calls (also sent as x-sume-poll-after). It is 2 seconds while a job runs and longer when a job is deferred. Images usually finish in 5–30 seconds; video in one to several minutes.
async function waitForJob(statusUrl, key) {
for (;;) {
const res = await fetch(statusUrl, { headers: { Authorization: `Bearer ${key}` } });
if (res.status === 429 || res.status >= 500) {
await sleep(Number(res.headers.get("retry-after") ?? 5) * 1000);
continue;
}
const { data } = await res.json();
if (data.terminal) return data;
await sleep((data.next_poll_after_seconds ?? 2) * 1000);
}
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));Set your own deadline per model. A job still running past it keeps running; check it again later instead of resubmitting.
Wait inside the submit
| mode | What happens |
|---|---|
async | Default. The submit answers at once; you poll. |
webhook | Sume POSTs the outcome to webhook_url. See Webhooks. |
sync | The submit waits up to wait_timeout_seconds (30 at most), then answers like async with sync.timed_out: true if the job is still running. |
Get the result
GEThttps://api.sume.com/v1/jobs/{id}/result
Returns the artifacts of a completed job. While the job is queued or processing it answers 409 job_not_completed: poll the status, then read again. A failed job answers 409 job_failed with the reason as the message, and a canceled one 409 job_canceled; neither will ever have a result.
{
"data": {
"request_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"job_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"status": "COMPLETED",
"result": {
"artifacts": [
{
"id": "artf_UCdnhWThU_Tbemv7E2gE7-ee9lNCIDxP",
"type": "image",
"url": "https://media.sume.com/artifacts/artf_UCdnhWThU_Tbemv7E2gE7-ee9lNCIDxP/images.png",
"content_type": "image/png",
"visibility": "public_by_link",
"size_bytes": 1354577,
"width": null,
"height": null,
"duration_ms": null
}
]
}
}
}Get and list jobs
GEThttps://api.sume.com/v1/jobs/{id}
The whole job: model, the inputs it ran with, timestamps, result, error and webhook delivery.
GEThttps://api.sume.com/v1/jobs
| Query | Description |
|---|---|
limit | 1–100 jobs per page, newest first. |
status | queued, processing, completed, failed or canceled. |
type | image_generation, video_generation… |
starting_after | The next_cursor from the previous page. |
curl "https://api.sume.com/v1/jobs?limit=20&status=completed" \
-H "Authorization: Bearer $SUME_API_KEY"A job stores its idempotency_key, so you can find a job you lost track of in the list.
Cancel
POSThttps://api.sume.com/v1/jobs/{id}/cancel
Works only before generation starts; the status says whether it still can (cancelable, cancel_url). Many models start within a second.
curl -X POST https://api.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/cancel \
-H "Authorization: Bearer $SUME_API_KEY"A job whose generation has started answers 409 job_generation_already_started; one that has already ended answers 409 job_not_cancelable.
{
"error": {
"code": "job_generation_already_started",
"message": "Generation has already started and can no longer be canceled.",
"request_id": "req_0ee311b4334e4b118a94c7d1c48577fd",
"category": "job_state",
"stage": "job_state",
"retryable": false,
"retry_after_seconds": null,
"public_reason": "job_generation_already_started",
"next_action": "inspect_events",
"details": {
"status": "processing",
"cancelable": false,
"reason": "generation_started"
}
}
}