Endpoints
Base URL https://api.sizzle.tools. "Key" means Authorization: Bearer $SIZZLE_KEY.
| Method | Path | What it does | Auth |
|---|---|---|---|
| GET | /v1/health | Answers {"ok":true} when the API is up. | None |
| GET | /v1/prices | Operations with prices and settings, packs, plans and wallet rules. See Price list. | None |
| POST | /v1/quote | The price of a job: the list price without a key, what your account pays with one. See Quote. | Optional |
| GET | /v1/me | Your account, wallet and the key you used. See Account. | Key |
| GET | /v1/wallet | Your credits. See Wallet. | Key |
| GET | /v1/wallet/history | Wallet entries, newest first. ?limit= 1 to 200 (default 50), ?before= a seq. | Key |
| POST | /v1/uploads | Upload a file (multipart/form-data, field file, up to 10 MB). 201 with an upload. | Key |
| DELETE | /v1/uploads/:id | Delete an upload now, or as soon as a running job no longer reads it. 204. | Key |
| POST | /v1/jobs | Create a job. 202 with the job; 200 when an Idempotency-Key repeats. | Key |
| GET | /v1/jobs | Your jobs, newest first: { "items": [...], "next_cursor": ... }. ?limit= 1 to 100 (default 20), ?cursor= from next_cursor. | Key |
| GET | /v1/jobs/:id | One job with fresh status and result links. | Key |
| DELETE | /v1/jobs/:id/files | Delete 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/current | Revoke the key that sends the call. 204; the next call gets 401. | Key |
| GET, PUT | /v1/me/email-preferences | Read or change the account’s email settings. See Email settings. | Key |
| POST | /v1/checkout | A checkout page link to buy credits. See Buying from code. | Key |
| POST | /v1/portal | A 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
{
"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"
}| Field | Notes |
|---|---|
id | job_ and 20 letters and digits. |
operation | The operation id. |
params | The settings used, with defaults filled in. Voice jobs also show characters and, on Fast, the voice. |
input | The source you sent: { "image": {...} }, { "video": {...} }, { "image": {...}, "garment": {...} }, { "text": { "characters", "sha256" } } (length and hash of the text) or {}. |
status | queued, running, succeeded or failed. See Job statuses. |
credits | Credits taken from the wallet. A failed job keeps showing them; the refund is in the wallet history. |
list_credits | The full price of the job. |
included | { "kind", "units" } when an Ultra allowance paid for it, for example { "kind": "voice characters", "units": 1800 }; otherwise null. |
output | The main result, or null until the job has succeeded. |
results | Every result, the main one first. |
error | null, or for a failed job { "code", "message", "credits_returned": true }. |
created_at, updated_at, finished_at | ISO 8601 times; finished_at is null until the job ends. |
Result
| Field | Notes |
|---|---|
type | video, audio or image. |
label | What 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). |
url | Signed link to the file, no key needed. null once the file has expired or was deleted. |
mime | video/mp4, audio/mpeg, image/png or image/jpeg. |
width, height | Pixels; null for audio, and for photos whose size we did not know. |
duration_s | Seconds for video and music; null for photos and voice. |
expires_at | When the link stops working, 24 hours after the file was made. |
expired | true after expires_at or after DELETE /v1/jobs/:id/files. |
ai_content | generated, 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"
}mimeis read from the bytes:image/jpeg,image/png,image/webp,image/gif,video/mp4orvideo/quicktime.sizeis in bytes.width,heightand, for clips,duration_sare read from the file and may benullwhen they cannot be read.- Use
upload_idasinputwithin 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
}| Field | Notes |
|---|---|
credits | What the job would take from your wallet now. Without a key: the list price. |
list_credits | The full price. |
covered_by | free, allowance, plan, pack or mixed; null without a key or without enough credits. |
enough | Whether the wallet covers it; null without a key. |
balance | Your credits now; null without a key. |
included | The Ultra allowance part, { "kind", "units" }, or null. |
Account
{
"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
}keydescribes the key that sent the call;platformisapifor a key made for your own code.free_credits.eligibleisfalsewhen the account gets no monthly free credits, with areasoncode when there is one (otherwisenull).holdisnull, or{ "status", "since" }while the account waits for a check (then writes answer403 account_on_hold).
Wallet
GET /v1/wallet returns the wallet object shown above.
| Field | Notes |
|---|---|
total | All 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_at | When plan and pack credits expire, 12 months after the latest purchase or renewal. |
{
"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) oradjust(a correction).bucket:free,plan,packorincluded(an Ultra allowance).- When
next_beforeis notnull, pass it as?before=for the next page.
Price list
{
"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"]
}
}creditsis the price with default settings.priceshows how it changes:{ "credits" }for a fixed price,{ "by", "credits": {...} }by a setting (duration,scale; upscale adds thereferenceclip size), or{ "credits", "per", "of", "rounding" }for voice.inputisimage,video,text,none,tryon,image_or_prompt(video: a photo, or no input withparams.prompt) ornone_or_video(music: no input, or a video to add the music to).paramsis a JSON Schema of the settings, with allowed values and defaults.- Voice operations also have
languages, see Voice.
Buying from code
Most people buy credits in the dashboard at app.sizzle.tools. If your tool needs a "Buy credits" button, a key can create the links. The person pays on the checkout page, which also asks them to accept the Terms.
curl -X POST https://api.sizzle.tools/v1/checkout \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-d '{"product":"pack_2200","currency":"usd","success_url":"https://example.com/thanks","cancel_url":"https://example.com/shop"}'product:pack_1000,pack_2200,pack_6000,plan_monthlyorplan_ultra.currency:usd(default) orpln.success_urlandcancel_url(or onereturn_urlfor both) must be https. Without them the page returns to sizzle.tools.- A plan while the account already has one gets
409 already_subscribed. POST /v1/portalwith an optionalreturn_urlreturns{ "url" }for the billing portal (card, invoices, cancelling a plan). Before the first purchase it answers409 no_billing_account.
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.
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.