Getting started

Sume API

Make images and video from your own code. One key, two generate endpoints, and every request turns into a job you poll or get called back about.

At a glance

Base URL	`https://api.dev.sume.com`
Auth	`Authorization: Bearer <key>`
Keys	Dashboard → API keys
Billing	Your workspace balance, in US dollars
Body	JSON in and out. Successful responses wrap the body in `data`, errors in `error`.

Make a request

This asks gpt-image-2 for one low-quality image, which costs under a cent. The call answers at once with a job; the image arrives a few seconds later.

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"
  }'

202 Accepted

{
  "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
  }
}

How a request runs

Submit. POST /v1/image-router/generate or /v1/video-router/generate with a model and its inputs. Sume checks the body, reserves the price and answers 202 with a job id.
Wait. Poll status_url until terminal is true, or pass a webhook_url and let Sume call you.
Read. GET result_url returns the artifacts, each with a download URL on media.sume.com. A failed job is refunded.

Where to go next

Formats and Actions

The Formats and Actions APIs have their own reference at docs.sume.com. These pages cover generation only.