Getting started
Quickstart
From a new key to a downloaded image in four calls. You need a Sume workspace with a little balance; this run costs under a cent.
1. Get a key
Open Dashboard → API keys, create a key and copy it. The full key is shown once. Keep it in your environment:
export SUME_API_KEY="sume_live_..."Server-side only
A key spends your workspace balance. Do not ship it in a browser bundle or a mobile app; call the API from your server.
2. Submit a job
Send the model and its inputs. The Idempotency-Key header makes a retry return the same job instead of a second charge.
curl -X POST https://api.dev.sume.com/v1/image-router/generate \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"model": "gpt-image-2",
"prompt": "A ceramic coffee cup on a wooden table, soft morning light",
"quality": "low",
"aspect_ratio": "1:1"
}'{
"data": {
"request_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"job": {
"id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"type": "image_generation",
"status": "queued",
"model": "gpt-image-2",
"created_at": "2026-10-21T02:31:52.075Z",
"result": null,
"error": null
},
"status_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
"result_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
"events_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/events",
"cancel_url": null,
"cancelable": false,
"next_action": "poll_status",
"next_poll_after_seconds": 2,
"terminal": false,
"idempotency_hit": false
}
}3. Poll the job
Call status_url until terminal is true, waiting next_poll_after_seconds between calls. The client libraries do this for you.
curl https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status \
-H "Authorization: Bearer $SUME_API_KEY"{
"data": {
"request_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"job_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"status": "COMPLETED",
"sume_status": "completed",
"status_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
"result_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
"cancel_url": null,
"cancelable": false,
"next_action": "fetch_result",
"next_poll_after_seconds": null,
"result_ready": true,
"terminal": true
}
}4. Read the result
When next_action is fetch_result, read result_url. Every artifact has a public URL; copy it to your own storage if you need to control access.
curl https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result \
-H "Authorization: Bearer $SUME_API_KEY"{
"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
}
]
}
}
}Other endings: failed (the job's error says why) and canceled. Both are refunded.