How it works
Every Sizzle app, plugin and the dashboard call the same API. With a key you can make videos, voice-overs, music, upscaled clips, product photos and try-on previews from your own code. Jobs are paid with credits from the same wallet you use in the dashboard (a credit is about 1 cent).
- Make a key in the dashboard.
- Upload a file, or point to one by its https URL.
- Check the price with
POST /v1/quote. - Create a job with
POST /v1/jobs. - Poll
GET /v1/jobs/:iduntil it has finished. - Download the result files within 24 hours.
The full walk-through with cURL examples is in Jobs and operations. Every endpoint and object is in the API reference.
Base URL and versions
All calls go to https://api.sizzle.tools. Every route starts with /v1.
curl https://api.sizzle.tools/v1/health- Request and response bodies are JSON. Uploads are
multipart/form-data. - Times are ISO 8601 strings in UTC, for example
2026-11-12T10:15:02.000Z. - Credits are whole numbers.
- Ids carry a prefix:
job_for jobs,up_for uploads. - New fields can appear in responses over time. Ignore the ones you do not use.
Authentication
Send your key in the Authorization header as a Bearer token on every call. Only GET /v1/health, GET /v1/prices, POST /v1/quote (key optional) and the signed result links work without one.
curl https://api.sizzle.tools/v1/me \
-H "Authorization: Bearer $SIZZLE_KEY"A missing, wrong or revoked key gets 401 unauthorized. A key spends the wallet of the account that made it: the same credits as your dashboard and your connected stores.
Get a key
- Sign in at app.sizzle.tools.
- Open Connections and click New key.
- Give the key a name, pick Own code under Used in and click Create.
- Copy the key. It is shown only once.
- Store it where your code reads secrets, for example in an environment variable
SIZZLE_KEY.
- Production keys start with
sz_live_. - An account can have up to 50 active keys. Make one per tool or server, so you can revoke one without touching the others.
- Under Daily limit you can cap how many credits a key may spend in a day. Over the cap the API answers
429 daily_limit. - We email you when a key is made. If the dashboard asks you to sign in again first, that is a safety check for new keys.
- Keys cannot make or list other keys. That needs a signed-in person in the dashboard.
Plugins and store apps connect without copying a key. See Connect your store.
Keep keys secret
A key spends your credits. Call the API from your server or script only, never from a web page or an app you ship to others. Browser code on your own website cannot call it directly anyway: the API does not accept cross-origin requests from other sites.
- Keep keys out of source code and public repositories. Read them from the environment.
- To revoke a key, click Disconnect next to it in Connections. It stops working at once and the next call gets
401. - A key can also revoke itself:
DELETE /v1/keys/currentwith that key answers204. - We email the account owner when a key starts working from a new country or spends a lot within an hour. The email has a link to disconnect it.
- If a key leaks, disconnect it and write to support@sizzle.tools. You are responsible for what is made with your keys (see the Terms).
Requests and responses
- Send JSON bodies with
Content-Type: application/json. A body that is not JSON gets400 invalid_request. - Uploads go to
POST /v1/uploadsasmultipart/form-datawith the file in a field namedfile. - Success codes:
200for reads,201for a new upload or checkout link,202for a new job,204for some deletes. - A field that is missing or not allowed gets
422 invalid_request, with each problem listed indetail.issuesas apathand amessage. - Job settings go in
params, the file or text to work on goes ininput. See Jobs and operations.
Errors
Every error has the same shape. code is stable and meant for your code; message is a short English sentence you can show to people; detail appears when there is more to say.
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits for this. Buy a pack or pick a plan to continue.",
"detail": { "needed": 300, "available": 50 }
}
}{
"error": {
"code": "invalid_request",
"message": "The request is not valid.",
"detail": {
"issues": [{ "path": "params.prompt", "message": "Describe the video, or send a photo as input." }]
}
}
}| Status | Code | When | What to do |
|---|---|---|---|
| 400 | invalid_request | The body is not JSON, or an upload is not multipart/form-data. | Fix the request. |
| 401 | unauthorized | No key, a wrong key or a revoked key. | Check the Authorization header. Make a new key if the old one was disconnected. |
| 402 | insufficient_credits | The wallet cannot cover the price. detail has needed and available. | Buy credits, or wait for the monthly free credits. |
| 403 | forbidden | The route needs a signed-in person (keys, sessions), or a result link was changed or has expired. | Manage keys in the dashboard. Use result links as the job gives them, before they expire. |
| 403 | account_on_hold | The account is waiting for a check. Reads work; new jobs, uploads and purchases do not. | Write to support@sizzle.tools. |
| 404 | not_found | Unknown route, or a job or upload that is not on your account. | Check the id and that you use the right key. |
| 409 | idempotency_conflict | The Idempotency-Key was already used for a different request. | Use a new key for a new request. |
| 409 | price_changed | expected_credits is not the price now. detail.credits has the price. | Accept the new price and send again. |
| 409 | job_active | You asked to delete the files of a job that is still queued or running. | Wait until the job has finished. |
| 409 | already_subscribed | A checkout link for a plan while the account has a plan. | Change the plan in the billing portal. |
| 409 | no_billing_account | A billing portal link before the first purchase. | Buy a pack or a plan first. |
| 422 | invalid_request | A field is missing, has a wrong value or does not fit the operation. See detail.issues. | Fix the field named in path. |
| 422 | unknown_operation | The operation does not exist. detail.operations lists the valid ids. | Use an id from the operations table. |
| 422 | file_too_large | The file is over 10 MB. detail.max_bytes has the limit. | Send a smaller file. |
| 422 | unsupported_file | Not a JPEG, PNG, WebP or GIF photo or an MP4 or MOV video, or the file is empty. | Convert the file. |
| 422 | input_unreachable | We could not download the image_url or video_url. | Make the file public over https, or upload it. |
| 422 | input_unusable | We could not read the length or frame size of the clip. | Send an MP4 or MOV file. |
| 422 | prompt_not_allowed | A prompt, scene, colour, lyrics or voice text asks for something not allowed. detail.category says what kind. | Describe a product, a scene or a mood instead. |
| 429 | rate_limited | Too many uploads in an hour, too many quotes without a key from one address, too many checkout links, or many jobs or credit changes of one account at the same moment (detail.reason: busy). | Wait a little and retry with a growing pause. With the same Idempotency-Key a retry is safe. |
| 429 | too_many_active_jobs | Too many of your jobs are queued or running. | Wait for one to finish, then send the next. |
| 429 | daily_limit | A daily limit of the account or of this key was reached. It resets at midnight UTC. | Raise the key’s limit in Connections, or write to us. |
| 429 | too_many_failures | Many of your jobs failed today. | Check your inputs and try again in a few hours. |
| 429 | prompt_blocked | Many prompts were refused in the last 24 hours. | Try again tomorrow. |
| 500 | internal | Something broke on our side. | Retry later. With the same Idempotency-Key a retry is safe. |
| 502, 503 | billing_unavailable | Payments do not work right now. | Retry later. |
| 503 | service_paused | Creating is paused for a short while. | Retry in a few hours. |
| 503 | free_paused | Jobs paid with free credits are paused. Paid credits still work. | Buy credits, or retry in a few hours. |
| 503 | operation_paused | One tool is paused. | Retry later, or use another tool. |
A job that was accepted but could not be made does not answer with an error status: it ends with status: "failed" and an error object. Those codes are listed under Job statuses.
Retrying safely
Send an Idempotency-Key header with POST /v1/jobs, for example a UUID or your own order id (at most 200 characters). If the connection drops, send the same request with the same key again: you get the job that was already made, with status 200 instead of 202, and you pay once.
- It is honoured on
POST /v1/jobsonly. Uploads and other calls ignore it. - The key belongs to your account and does not expire: it is stored with the job, so it keeps pointing to that job.
- The same key with a different operation, settings or input gets
409 idempotency_conflict. - A replay returns the job as it is now, also when it has failed. To try a failed job again, use a new key.
curl -X POST https://api.sizzle.tools/v1/jobs \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-photo-1" \
-d '{"operation":"photo.cleanup","params":{"background":"white"},"input":{"image_url":"https://example.com/photo.jpg"}}'Limits
| What | Limit | Answer when over |
|---|---|---|
| Jobs queued or running at once | 3 for an account that has never paid, 20 after the first payment | 429 too_many_active_jobs |
| Uploads | 300 per account per hour | 429 rate_limited |
| File size | 10 MB per file, uploaded or fetched from a URL | 422 file_too_large |
| File types | JPEG, PNG, WebP, GIF, MP4 and MOV, read from the file itself | 422 unsupported_file |
| Files given by URL | https only, public, answering within 30 seconds | 422 input_unreachable (422 invalid_request for a URL that is not https) |
| Voice text | Up to 200,000 characters per job | 422 invalid_request |
| Active keys | 50 per account | 422 too_many_keys in the dashboard |
| Daily limits | Per account, and per key when you set one in Connections; reset at midnight UTC | 429 daily_limit |
| Failed jobs | Many failed jobs in one day pause new ones | 429 too_many_failures |
| Refused prompts | Many refusals in 24 hours block jobs with a prompt for a while | 429 prompt_blocked |
| Quotes without a key | Limited per IP address; send your key to avoid it | 429 rate_limited |
| Safety limits for the whole service | Daily limits on what Sizzle makes in total and from free credits | 503 service_paused, 503 free_paused, 503 operation_paused |
The numbers are today’s defaults and can change. Limits never stop a refund: a failed job always gets its credits back. On 429 and 503, wait and retry with a growing pause. Each operation has its own limits on input size and length, listed in Jobs and operations.
Credits
- A credit is about 1 cent. Prices per operation are in the operations table and in
GET /v1/prices. - Accounts get 50 free credits each calendar month (UTC);
free_creditsinGET /v1/meshows whether yours does. Unused free credits do not carry over. - Paid credits (packs and plans) are valid for 12 months from your latest purchase or plan renewal.
- Buy credits in the dashboard at app.sizzle.tools. Packs and plans are on the pricing page, and Credits and billing explains the rest.
When you create a job, its full price is reserved from your wallet at once, so two jobs can never spend the same credits. Credits are taken in this order: a matching Ultra plan allowance, then free credits, then plan credits, then pack credits.
- Succeeded: the job keeps the credits it reserved.
- Failed or timed out: every credit goes back to where it came from, automatically. The wallet history shows a
refundentry and the job’serror.credits_returnedistrue. - Not enough credits: the job is not made and you get
402 insufficient_credits. Nothing is reserved.
To be sure you pay the price you showed someone, send it as expected_credits when you create the job. If the price differs, the job is not made and you get 409 price_changed.
Files and result links
- Uploads and files fetched from your URLs are kept for 24 hours, then deleted.
- Results are kept for 24 hours. Each result has a signed link on
https://api.sizzle.tools/v1/files/that works without a key until itsexpires_at. - After that the result shows
url: nullandexpired: true. Download what you need and keep your own copy. - Links support HTTP range requests, so a video can be streamed and scrubbed.
- You can delete files sooner:
DELETE /v1/uploads/:idfor an upload,DELETE /v1/jobs/:id/filesfor a finished job’s results and the uploads it used byupload_id. - Files of a job named in an abuse report are not deleted after 24 hours: they are kept for up to 30 days while we review the report, and 30 days more if we act on it. Their links still expire as usual.
Each result also says whether it is AI content in ai_content: generated (video, music, voice, try-on, image from text), edited (new scene, colour change) or null (upscale, clean-up). Generated and edited PNG, JPEG and MP4 files carry the same label in their metadata (IPTC digital source type in XMP). Label AI content where the law or a marketplace asks for it.
Still stuck? Write to support@sizzle.tools.