API reference

The endpoints you can call with a key, and the objects they return.

Endpoints

Base URL https://api.sizzle.tools. "Key" means Authorization: Bearer $SIZZLE_KEY.

MethodPathWhat it doesAuth
GET/v1/healthAnswers {"ok":true} when the API is up.None
GET/v1/pricesOperations with prices and settings, packs, plans and wallet rules. See Price list.None
POST/v1/quoteThe price of a job: the list price without a key, what your account pays with one. See Quote.Optional
GET/v1/meYour account, wallet and the key you used. See Account.Key
GET/v1/walletYour credits. See Wallet.Key
GET/v1/wallet/historyWallet entries, newest first. ?limit= 1 to 200 (default 50), ?before= a seq.Key
POST/v1/uploadsUpload a file (multipart/form-data, field file, up to 10 MB). 201 with an upload.Key
DELETE/v1/uploads/:idDelete an upload now, or as soon as a running job no longer reads it. 204.Key
POST/v1/jobsCreate a job. 202 with the job; 200 when an Idempotency-Key repeats.Key
GET/v1/jobsYour jobs, newest first: { "items": [...], "next_cursor": ... }. ?limit= 1 to 100 (default 20), ?cursor= from next_cursor.Key
GET/v1/jobs/:idOne job with fresh status and result links.Key
DELETE/v1/jobs/:id/filesDelete a finished job’s result files and the uploads it used by upload_id: {"deleted":true}.Key
GET/v1/files/...A result file, from the signed url of a result. Supports range requests.Signed link
DELETE/v1/keys/currentRevoke the key that sends the call. 204; the next call gets 401.Key
GET, PUT/v1/me/email-preferencesRead or change the account’s email settings. See Email settings.Key
POST/v1/checkoutA checkout page link to buy credits. See Buying from code.Key
POST/v1/portalA billing portal link: card, invoices, plan.Key

Routes for managing keys and sign-in sessions need a person signed in to the dashboard: a key gets 403 forbidden there.

Job

A white-background clean-up of a 1600×2000 upload.
{
  "id": "job_p5r8t2w6y9a1d4g7j0mq",
  "operation": "photo.cleanup",
  "params": { "background": "white" },
  "input": { "image": { "upload_id": "up_7h2m9q4x1k8c3v6b0n5z" } },
  "status": "succeeded",
  "credits": 2,
  "list_credits": 2,
  "included": null,
  "output": {
    "type": "image",
    "label": "photo",
    "url": "https://api.sizzle.tools/v1/files/results/job_p5r8t2w6y9a1d4g7j0mq/4.jpg?exp=1794564920&sig=02af456d59c783d346720e254995ed97ac46aa46940abac7bd6d34ad52cec138",
    "mime": "image/jpeg",
    "width": 3276,
    "height": 4096,
    "duration_s": null,
    "expires_at": "2026-11-13T10:15:20.000Z",
    "expired": false,
    "ai_content": null
  },
  "results": [
    {
      "type": "image",
      "label": "photo",
      "url": "https://api.sizzle.tools/v1/files/results/job_p5r8t2w6y9a1d4g7j0mq/4.jpg?exp=1794564920&sig=02af456d59c783d346720e254995ed97ac46aa46940abac7bd6d34ad52cec138",
      "mime": "image/jpeg",
      "width": 3276,
      "height": 4096,
      "duration_s": null,
      "expires_at": "2026-11-13T10:15:20.000Z",
      "expired": false,
      "ai_content": null
    }
  ],
  "error": null,
  "created_at": "2026-11-12T10:15:02.000Z",
  "updated_at": "2026-11-12T10:15:21.000Z",
  "finished_at": "2026-11-12T10:15:21.000Z"
}
FieldNotes
idjob_ and 20 letters and digits.
operationThe operation id.
paramsThe settings used, with defaults filled in. Voice jobs also show characters and, on Fast, the voice.
inputThe source you sent: { "image": {...} }, { "video": {...} }, { "image": {...}, "garment": {...} }, { "text": { "characters", "sha256" } } (length and hash of the text) or {}.
statusqueued, running, succeeded or failed. See Job statuses.
creditsCredits taken from the wallet. A failed job keeps showing them; the refund is in the wallet history.
list_creditsThe full price of the job.
included{ "kind", "units" } when an Ultra allowance paid for it, for example { "kind": "voice characters", "units": 1800 }; otherwise null.
outputThe main result, or null until the job has succeeded.
resultsEvery result, the main one first.
errornull, or for a failed job { "code", "message", "credits_returned": true }.
created_at, updated_at, finished_atISO 8601 times; finished_at is null until the job ends.

Result

FieldNotes
typevideo, audio or image.
labelWhat the file is: video, take-1 to take-3 (music on its own), music (the track added to a video), voice, photo, preview (try-on) or image (image from text).
urlSigned link to the file, no key needed. null once the file has expired or was deleted.
mimevideo/mp4, audio/mpeg, image/png or image/jpeg.
width, heightPixels; null for audio, and for photos whose size we did not know.
duration_sSeconds for video and music; null for photos and voice.
expires_atWhen the link stops working, 24 hours after the file was made.
expiredtrue after expires_at or after DELETE /v1/jobs/:id/files.
ai_contentgenerated, edited or null. See Files and result links.

A link that was changed or has expired answers 403 forbidden; a deleted file answers 404 not_found.

Upload

{
  "upload_id": "up_7h2m9q4x1k8c3v6b0n5z",
  "mime": "image/jpeg",
  "size": 482113,
  "width": 1600,
  "height": 2000,
  "duration_s": null,
  "expires_at": "2026-11-13T10:14:55.000Z"
}
  • mime is read from the bytes: image/jpeg, image/png, image/webp, image/gif, video/mp4 or video/quicktime.
  • size is in bytes. width, height and, for clips, duration_s are read from the file and may be null when they cannot be read.
  • Use upload_id as input within 24 hours, on the same account.

Quote

Request body: { "operation", "params", "input" }, the same as a job. input matters for upscale (the clip) and voice (the text); params.characters can stand in for voice text.

{
  "operation": "video.studio",
  "credits": 50,
  "list_credits": 50,
  "covered_by": "free",
  "enough": true,
  "balance": 50,
  "included": null
}
FieldNotes
creditsWhat the job would take from your wallet now. Without a key: the list price.
list_creditsThe full price.
covered_byfree, allowance, plan, pack or mixed; null without a key or without enough credits.
enoughWhether the wallet covers it; null without a key.
balanceYour credits now; null without a key.
includedThe Ultra allowance part, { "kind", "units" }, or null.

Account

GET /v1/me with a key made in the dashboard.
{
  "account": { "id": "acc_r2d9k4m8p1x7c3v6b5n0", "platform": "web", "name": null, "email": "you@example.com" },
  "wallet": {
    "total": 1035,
    "free": { "credits": 35, "resets_at": "2026-12-01T00:00:00.000Z" },
    "plan": null,
    "allowances": null,
    "packs": { "credits": 1000, "expires_at": "2027-11-10T09:12:44.000Z" },
    "paid_credits_expire_at": "2027-11-10T09:12:44.000Z"
  },
  "key": { "id": "key_w8n3c6v1b9m4x2k7q5z0", "label": "Catalog script", "platform": "api", "site_url": null, "source": "dashboard" },
  "trial": null,
  "reviewer": false,
  "free_credits": { "eligible": true, "reason": null },
  "hold": null
}
  • key describes the key that sent the call; platform is api for a key made for your own code.
  • free_credits.eligible is false when the account gets no monthly free credits, with a reason code when there is one (otherwise null).
  • hold is null, or { "status", "since" } while the account waits for a check (then writes answer 403 account_on_hold).

Wallet

GET /v1/wallet returns the wallet object shown above.

FieldNotes
totalAll credits you can spend now.
free{ "credits", "resets_at" }: this month’s free credits and when the next ones come.
plan{ "id", "name", "status", "credits", "renews_at", "ends_at" }, or null without a plan. id is plan_monthly or plan_ultra; ends_at is set when the plan was cancelled. When a plan has ended but its credits remain, status is ended and id is null.
allowances{ "photo", "music", "voice" }, each { "remaining", "expires_at" }, while an Ultra plan has allowance left; otherwise null.
packs{ "credits", "expires_at" } for pack credits, or null.
paid_credits_expire_atWhen plan and pack credits expire, 12 months after the latest purchase or renewal.
GET /v1/wallet/history: a failed job refunded, then a clean-up.
{
  "entries": [
    { "seq": 4, "at": "2026-11-12T10:15:02.000Z", "kind": "reserve", "bucket": "free", "amount": -2, "job_id": "job_p5r8t2w6y9a1d4g7j0mq", "purchase_id": null },
    { "seq": 3, "at": "2026-11-11T16:41:30.000Z", "kind": "refund", "bucket": "free", "amount": 15, "job_id": "job_x1c4v7b2n5m8k3j6h9g0", "purchase_id": null },
    { "seq": 2, "at": "2026-11-11T16:40:02.000Z", "kind": "reserve", "bucket": "free", "amount": -15, "job_id": "job_x1c4v7b2n5m8k3j6h9g0", "purchase_id": null },
    { "seq": 1, "at": "2026-11-11T16:39:50.000Z", "kind": "grant", "bucket": "free", "amount": 50, "job_id": null, "purchase_id": null }
  ],
  "next_before": null
}
  • kind: grant (credits added), reserve (a job), refund (a failed job), expire, rollover_cap (plan credits over the rollover limit) or adjust (a correction).
  • bucket: free, plan, pack or included (an Ultra allowance).
  • When next_before is not null, pass it as ?before= for the next page.

Price list

Shortened: the real list has all 14 operations.
{
  "credit": { "approx_usd": 0.01 },
  "operations": [
    {
      "operation": "photo.cleanup",
      "label": "Photo Clean-up",
      "app": "photo",
      "tier": "Clean-up",
      "description": "Background removal and 4× upscale",
      "credits": 2,
      "unit": "per photo",
      "price": { "credits": 2 },
      "input": "image",
      "params": {
        "type": "object",
        "properties": {
          "background": { "default": "transparent", "type": "string", "enum": ["transparent", "white"] }
        }
      },
      "ai_content": null,
      "included_in_plans": ["ultra"],
      "included_kind": "photo clean-ups"
    }
  ],
  "packs": [
    { "id": "pack_1000", "credits": 1000, "price": { "usd": 9, "pln": 39 } },
    { "id": "pack_2200", "credits": 2200, "price": { "usd": 19, "pln": 79 } },
    { "id": "pack_6000", "credits": 6000, "price": { "usd": 49, "pln": 199 } }
  ],
  "plans": [
    { "id": "plan_monthly", "name": "Monthly", "credits_per_month": 2500, "price": { "usd": 19, "pln": 79 }, "included_per_month": {} },
    {
      "id": "plan_ultra",
      "name": "Ultra",
      "credits_per_month": 12000,
      "price": { "usd": 99, "pln": 399 },
      "included_per_month": { "photo clean-ups": 2000, "Fast music tracks": 300, "voice characters": 500000 }
    }
  ],
  "rules": {
    "free_credits_per_month": 50,
    "free_credits_carry_over": false,
    "plan_rollover_cap_months": 2,
    "paid_credits_valid_months": 12,
    "failed_generation_refund": "automatic",
    "spend_order": ["included", "free", "plan", "pack"]
  }
}
  • credits is the price with default settings. price shows how it changes: { "credits" } for a fixed price, { "by", "credits": {...} } by a setting (duration, scale; upscale adds the reference clip size), or { "credits", "per", "of", "rounding" } for voice.
  • input is image, video, text, none, tryon, image_or_prompt (video: a photo, or no input with params.prompt) or none_or_video (music: no input, or a video to add the music to).
  • params is a JSON Schema of the settings, with allowed values and defaults.
  • Voice operations also have languages, see Voice.

Email settings

Jobs that take more than 2 minutes send the account owner a "result ready" email, also when they come from your code. These service emails can be turned off.

Answers { "service": false, "marketing": false } with the settings now.
curl -X PUT https://api.sizzle.tools/v1/me/email-preferences \
  -H "Authorization: Bearer $SIZZLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service":false}'
  • service: results ready, low credits, new free credits. On by default.
  • marketing: Sizzle news and offers. Off unless the person agreed.
  • Emails about purchases, keys and account safety always go out.

Error codes

Every error is { "error": { "code", "message", "detail"? } }. The full table of codes, with what to do about each, is in API basics. Codes of failed jobs are under Job statuses.

Still stuck? Write to support@sizzle.tools.