Sizzle API basics

One HTTP API makes every Sizzle result, and your own code can call it with a key from your dashboard.

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).

  1. Make a key in the dashboard.
  2. Upload a file, or point to one by its https URL.
  3. Check the price with POST /v1/quote.
  4. Create a job with POST /v1/jobs.
  5. Poll GET /v1/jobs/:id until it has finished.
  6. 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.

Answers {"ok":true} when the API is up. No key needed.
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.

Returns your account, your wallet and the key you used.
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

  1. Sign in at app.sizzle.tools.
  2. Open Connections and click New key.
  3. Give the key a name, pick Own code under Used in and click Create.
  4. Copy the key. It is shown only once.
  5. 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/current with that key answers 204.
  • 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 gets 400 invalid_request.
  • Uploads go to POST /v1/uploads as multipart/form-data with the file in a field named file.
  • Success codes: 200 for reads, 201 for a new upload or checkout link, 202 for a new job, 204 for some deletes.
  • A field that is missing or not allowed gets 422 invalid_request, with each problem listed in detail.issues as a path and a message.
  • Job settings go in params, the file or text to work on goes in input. 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." }]
    }
  }
}
StatusCodeWhenWhat to do
400invalid_requestThe body is not JSON, or an upload is not multipart/form-data.Fix the request.
401unauthorizedNo key, a wrong key or a revoked key.Check the Authorization header. Make a new key if the old one was disconnected.
402insufficient_creditsThe wallet cannot cover the price. detail has needed and available.Buy credits, or wait for the monthly free credits.
403forbiddenThe 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.
403account_on_holdThe account is waiting for a check. Reads work; new jobs, uploads and purchases do not.Write to support@sizzle.tools.
404not_foundUnknown route, or a job or upload that is not on your account.Check the id and that you use the right key.
409idempotency_conflictThe Idempotency-Key was already used for a different request.Use a new key for a new request.
409price_changedexpected_credits is not the price now. detail.credits has the price.Accept the new price and send again.
409job_activeYou asked to delete the files of a job that is still queued or running.Wait until the job has finished.
409already_subscribedA checkout link for a plan while the account has a plan.Change the plan in the billing portal.
409no_billing_accountA billing portal link before the first purchase.Buy a pack or a plan first.
422invalid_requestA field is missing, has a wrong value or does not fit the operation. See detail.issues.Fix the field named in path.
422unknown_operationThe operation does not exist. detail.operations lists the valid ids.Use an id from the operations table.
422file_too_largeThe file is over 10 MB. detail.max_bytes has the limit.Send a smaller file.
422unsupported_fileNot a JPEG, PNG, WebP or GIF photo or an MP4 or MOV video, or the file is empty.Convert the file.
422input_unreachableWe could not download the image_url or video_url.Make the file public over https, or upload it.
422input_unusableWe could not read the length or frame size of the clip.Send an MP4 or MOV file.
422prompt_not_allowedA 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.
429rate_limitedToo 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.
429too_many_active_jobsToo many of your jobs are queued or running.Wait for one to finish, then send the next.
429daily_limitA 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.
429too_many_failuresMany of your jobs failed today.Check your inputs and try again in a few hours.
429prompt_blockedMany prompts were refused in the last 24 hours.Try again tomorrow.
500internalSomething broke on our side.Retry later. With the same Idempotency-Key a retry is safe.
502, 503billing_unavailablePayments do not work right now.Retry later.
503service_pausedCreating is paused for a short while.Retry in a few hours.
503free_pausedJobs paid with free credits are paused. Paid credits still work.Buy credits, or retry in a few hours.
503operation_pausedOne 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/jobs only. 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

WhatLimitAnswer when over
Jobs queued or running at once3 for an account that has never paid, 20 after the first payment429 too_many_active_jobs
Uploads300 per account per hour429 rate_limited
File size10 MB per file, uploaded or fetched from a URL422 file_too_large
File typesJPEG, PNG, WebP, GIF, MP4 and MOV, read from the file itself422 unsupported_file
Files given by URLhttps only, public, answering within 30 seconds422 input_unreachable (422 invalid_request for a URL that is not https)
Voice textUp to 200,000 characters per job422 invalid_request
Active keys50 per account422 too_many_keys in the dashboard
Daily limitsPer account, and per key when you set one in Connections; reset at midnight UTC429 daily_limit
Failed jobsMany failed jobs in one day pause new ones429 too_many_failures
Refused promptsMany refusals in 24 hours block jobs with a prompt for a while429 prompt_blocked
Quotes without a keyLimited per IP address; send your key to avoid it429 rate_limited
Safety limits for the whole serviceDaily limits on what Sizzle makes in total and from free credits503 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_credits in GET /v1/me shows 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 refund entry and the job’s error.credits_returned is true.
  • 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 its expires_at.
  • After that the result shows url: null and expired: 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/:id for an upload, DELETE /v1/jobs/:id/files for a finished job’s results and the uploads it used by upload_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.