The workflow
- Upload a file, or use a public https URL (optional: text and music need no file).
- Check the price with
POST /v1/quote. - Create the job with
POST /v1/jobs. - Poll
GET /v1/jobs/:iduntil the status issucceededorfailed. - Download the files from
resultsbefore they expire. - Delete the files early if you need to.
The examples use cURL with your key in $SIZZLE_KEY. API basics covers keys, errors and limits.
1. Send the file
Upload a photo or a clip of up to 10 MB. The type is read from the file itself: JPEG, PNG, WebP or GIF photos, MP4 or MOV video.
curl -X POST https://api.sizzle.tools/v1/uploads \
-H "Authorization: Bearer $SIZZLE_KEY" \
-F file=@photo.jpg{
"upload_id": "up_7h2m9q4x1k8c3v6b0n5z",
"mime": "image/jpeg",
"size": 482113,
"width": 1600,
"height": 2000,
"duration_s": null,
"expires_at": "2026-11-13T10:14:55.000Z"
}The job’s input names one source:
| Input | Use it for |
|---|---|
{ "upload_id": "up_..." } | A file from POST /v1/uploads. |
{ "image_url": "https://..." } | A public photo. We download it once when the job is made (up to 10 MB) and use our copy. |
{ "video_url": "https://..." } | A public MP4 or MOV clip, the same way. |
{ "job_id": "job_..." } | The result of an earlier job on your account, for example a video to upscale. It must have succeeded and not expired. |
{ "text": "..." } | The text for a voice-over. |
no input, or {} | Music, image from text, and video from a text prompt. |
Try-on takes two photos: the person as above, plus garment with its own image_url, upload_id or job_id. Send only one source per photo; two get 422.
2. Check the price
curl -X POST https://api.sizzle.tools/v1/quote \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"photo.cleanup","params":{"background":"white"}}'{
"operation": "photo.cleanup",
"credits": 2,
"list_credits": 2,
"covered_by": "free",
"enough": true,
"balance": 50,
"included": null
}creditsis what this job would take from your wallet now;list_creditsis the full price.covered_bysays where the credits would come from:free,allowance,plan,packormixed.enoughsays whether you have them.- Without a key you get the list price, with
covered_by,enoughandbalanceset tonull. - For voice, send the text as
input.text, or just its length asparams.characters. - For upscale, send the clip as
inputwith your key: the price depends on its size and length. - A prompt is not needed for a quote: it does not change the price.
3. Create the job
| Field | What it is |
|---|---|
operation | Required. One of the ids in the operations table. |
params | Settings of the operation. Leave a setting out to get its default. |
input | The file or text to work on, see Send the file. |
expected_credits | Optional. The price you expect; a different price gets 409 price_changed. |
curl -X POST https://api.sizzle.tools/v1/jobs \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mug-video-1" \
-d '{"operation":"video.fast","params":{"prompt":"A ceramic mug on a wooden table, slow orbit","duration":10},"expected_credits":25}'{
"id": "job_k3x9q2m7v1c8b4n6z0wd",
"operation": "video.fast",
"params": { "duration": 10, "prompt": "A ceramic mug on a wooden table, slow orbit" },
"input": {},
"status": "queued",
"credits": 25,
"list_credits": 25,
"included": null,
"output": null,
"results": [],
"error": null,
"created_at": "2026-11-12T10:20:00.000Z",
"updated_at": "2026-11-12T10:20:00.000Z",
"finished_at": null
}Everything is checked before credits are reserved: the settings, the input (owner, expiry, file type, size, length) and the text. If anything is wrong you get an error and nothing is charged.
Prompts, scenes and colours can be written in any language: they are translated into English before generation, and the job keeps what you wrote. Lyrics and voice texts are used as written.
Prompts, scenes, colours, lyrics and voice texts are checked against our content rules. Sexual content or nudity, gore or shocking violence, real named people and political campaign material get 422 prompt_not_allowed, with detail.category set to sexual, violence, real_person or political. Repeated refusals block jobs with a prompt for a while.
4. Wait for the result
JOB=job_k3x9q2m7v1c8b4n6z0wd
while true; do
STATUS=$(curl -s "https://api.sizzle.tools/v1/jobs/$JOB" \
-H "Authorization: Bearer $SIZZLE_KEY" | jq -r .status)
echo "$STATUS"
[ "$STATUS" = queued ] || [ "$STATUS" = running ] || break
sleep 5
donePoll every 3 to 5 seconds for photos, voice and music, and every 10 to 20 seconds for upscale and video: we check those jobs about that often, so faster polling shows nothing new. GET /v1/jobs lists your jobs, newest first.
// Node 18 or newer
const API = 'https://api.sizzle.tools/v1';
const auth = { Authorization: 'Bearer ' + process.env.SIZZLE_KEY };
async function runJob(body, idempotencyKey) {
const res = await fetch(API + '/jobs', {
method: 'POST',
headers: { ...auth, 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
body: JSON.stringify(body),
});
let job = await res.json();
if (!res.ok) throw new Error(job.error.code + ': ' + job.error.message);
while (job.status === 'queued' || job.status === 'running') {
await new Promise((resolve) => setTimeout(resolve, 5000));
job = await (await fetch(API + '/jobs/' + job.id, { headers: auth })).json();
}
if (job.status === 'failed') throw new Error(job.error.code + ': ' + job.error.message);
return job.results; // download every url before its expires_at
}Job statuses
| Status | What it means |
|---|---|
queued | Accepted, credits reserved, waiting to start. |
running | Being made. |
succeeded | Done. The files are in output and results, and the credits stay spent. |
failed | Could not be made. error says why and every credit is back in your wallet. |
A failed job keeps its price in credits; the refund shows in your wallet history. Its error looks like this:
{
"code": "generation_failed",
"message": "We could not make this result. Your credits are back in your wallet.",
"credits_returned": true
}| `error.code` | Why |
|---|---|
generation_failed | The result could not be made from this input or these settings. |
timeout | It took too long and was stopped. |
unavailable | Generation was unavailable for a while. Try again later. |
input_unusable | The file could not be read. |
Time limits per job: video 40 minutes, upscale and Studio voice 30, Fast voice 20, photo, try-on and music 15. Steps that fail for a passing reason are retried before a job fails.
5. Read the results
output is the main file and results lists every file, with the main one first. A Fast video, for example, has one file, the video:
{
"id": "job_k3x9q2m7v1c8b4n6z0wd",
"operation": "video.fast",
"params": { "duration": 10, "prompt": "A ceramic mug on a wooden table, slow orbit" },
"input": {},
"status": "succeeded",
"credits": 25,
"list_credits": 25,
"included": null,
"output": {
"type": "video",
"label": "video",
"url": "https://api.sizzle.tools/v1/files/results/job_k3x9q2m7v1c8b4n6z0wd/1.mp4?exp=1794565384&sig=49da54e306e5a10a496d0c80166e18c16a042e9196cbde03a0506c5e17c594db",
"mime": "video/mp4",
"width": 576,
"height": 1024,
"duration_s": 10,
"expires_at": "2026-11-13T10:23:04.000Z",
"expired": false,
"ai_content": "generated"
},
"results": [
{
"type": "video",
"label": "video",
"url": "https://api.sizzle.tools/v1/files/results/job_k3x9q2m7v1c8b4n6z0wd/1.mp4?exp=1794565384&sig=49da54e306e5a10a496d0c80166e18c16a042e9196cbde03a0506c5e17c594db",
"mime": "video/mp4",
"width": 576,
"height": 1024,
"duration_s": 10,
"expires_at": "2026-11-13T10:23:04.000Z",
"expired": false,
"ai_content": "generated"
}
],
"error": null,
"created_at": "2026-11-12T10:20:00.000Z",
"updated_at": "2026-11-12T10:23:05.000Z",
"finished_at": "2026-11-12T10:23:05.000Z"
}curl -s "https://api.sizzle.tools/v1/jobs/$JOB" -H "Authorization: Bearer $SIZZLE_KEY" \
| jq -r .output.url | xargs curl -s -o video.mp4Every result has type (video, audio or image), label, url, mime, width and height (null for audio), duration_s (null for photos and voice), expires_at, expired and ai_content. Field notes are in the API reference.
6. Delete files early
Files go by themselves after 24 hours. If your host or your own policy needs them gone sooner:
# one upload: 204, also when it was deleted before
curl -X DELETE https://api.sizzle.tools/v1/uploads/up_7h2m9q4x1k8c3v6b0n5z \
-H "Authorization: Bearer $SIZZLE_KEY"
# a finished job's result files and the uploads it used: {"deleted":true}
curl -X DELETE https://api.sizzle.tools/v1/jobs/job_k3x9q2m7v1c8b4n6z0wd/files \
-H "Authorization: Bearer $SIZZLE_KEY"- An upload that a running job still reads is deleted the moment that job no longer needs it.
- Deleting a job’s files while it is queued or running gets
409 job_active. - The job stays in your history with its results marked
expired: trueandurl: null. Credits do not change. - Inputs you gave as
image_urlorvideo_urlare not removed by this call; our copies of them go after 24 hours. Upload a file and pass itsupload_idif you need it gone sooner.
Operations
These are all the operations, with the prices of today. GET /v1/prices returns the same list with each operation’s settings as JSON Schema, so your code can read prices instead of hard-coding them.
| Operation | What it makes | Input | Main settings | Credits | Output |
|---|---|---|---|---|---|
video.fast | Vertical video, no sound | Photo, or none with prompt | duration 5 or 10 (default 5), prompt | 20 (5 s), 25 (10 s) | MP4 576×1024, 24 fps |
video.studio | Landscape video with its own sound | Photo, or none with prompt | duration 5 or 10, prompt | 50 (5 s), 80 (10 s) | MP4 1344×768, 24 fps |
video.pro | Video with the best motion | Photo, or none with prompt | duration 5 or 10, prompt, aspect 9:16 (default) or 16:9 | 300 (5 s), 600 (10 s) | MP4 720×1280 or 1280×720, 24 fps |
upscale.fast | Sharper, bigger clip | Clip up to 10 s | scale 2 (default) or 4 | 5 (2×), 20 (4×) up to 576×1024 and 10 s; bigger clips more | MP4, each side times scale |
upscale.studio | Upscale with extra detail | Clip up to 10 s | scale 2 or 4 | 30 (2×), 110 (4×), same rule | MP4, each side times scale |
music.fast | Music track, quick sketch, or music for a video | None, or a video up to 60 s | prompt or mood, duration 10 to 60 s (default 30), vocals, lyrics, vocal_language | 5 | 3 MP3 takes; with a video: the video with music plus the MP3 |
music.studio | Music track, richer mix, or music for a video | None, or a video up to 60 s | Same as Fast | 15 | Same as Fast, tracks at least 20 s |
voice.fast | Voice-over at low cost | Text | language (6, default en), voice | 5 per 10,000 characters | One MP3 |
voice.studio | More natural voice-over | Text | language (23, default en) | 30 per 10,000 characters | One MP3 |
photo.cleanup | Background removal and 4× upscale | Photo | background transparent (default) or white | 2 | PNG with transparency, or JPEG on pure white; up to 4096 px |
photo.scene | Your product in a new setting | Photo | scene, 2 to 200 characters | 5 | PNG up to 1536 px, same proportions |
photo.color | Your product in another colour | Photo | color, 2 to 40 characters (required) | 5 | PNG up to 1536 px, same proportions |
tryon | The person wearing the garment | Person photo plus garment photo | None | 8 | PNG preview up to 1536 px |
image.generate | New image from a description | None | prompt 1 to 1000 characters (required), aspect | 3 | PNG 1024×1024, 896×1120, 720×1280 or 1280×720 |
Ultra plans include photo clean-ups, Fast music tracks and voice characters each month. A job those cover takes no credits for the covered part and shows it in included, for example { "kind": "photo clean-ups", "units": 1 }.
Video
- From a photo: send the product photo as
input. It must be at least 64 px on each side and at most 5000 px on the longer side.promptis then an optional hint for the motion. - From text: send no
inputand describe the video inparams.prompt(1 to 1000 characters after trimming). Without a photo and without a prompt you get422atparams.prompt. The price and size are the same as from a photo. durationis 5 or 10 seconds. Fast costs 20 credits for 5 seconds and 25 for 10.- Fast videos have no sound. To add music, run
music.fastormusic.studiowith the video asinput(see Music). - Studio is 16:9 with its own sound. Pro is 9:16 or 16:9, set with
aspect.
Fast videos are 576×1024. For Reels, which need at least 720 px, upscale the finished video 2× by its job id: 5 credits for 1152×2048.
curl -X POST https://api.sizzle.tools/v1/jobs \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mug-video-1-upscale" \
-d '{"operation":"upscale.fast","params":{"scale":2},"input":{"job_id":"job_k3x9q2m7v1c8b4n6z0wd"}}'Voice
Send the text as input.text and the language as params.language (ISO 639-1 code, default en). The price is proportional to the characters, rounded up to a whole credit per job: 2,000 characters cost 1 credit on Fast and 6 on Studio. It does not depend on the language.
curl -X POST https://api.sizzle.tools/v1/jobs \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: post-118-voice" \
-d '{"operation":"voice.fast","params":{"language":"es","voice":"alex"},"input":{"text":"Hola. Este es nuestro nuevo bolso de cuero."}}'Read the current languages and voices from the price list, so your code never falls behind:
curl -s https://api.sizzle.tools/v1/prices \
| jq '.operations[] | select(.operation == "voice.fast") | .languages'[
{
"code": "fr",
"name": { "en": "French", "pl": "francuski" },
"default_voice": "siwis",
"voices": [{ "id": "siwis", "name": "Siwis", "gender": "female", "locale": "fr-FR" }]
}
]| Fast language | Default voice | Voices |
|---|---|---|
en English | sky | US: alloy, aoede, bella, heart, jessica, kore, nicole, nova, river, sarah, sky, adam, echo, eric, fenrir, liam, michael, onyx, puck, santa. UK: alice, emma, isabella, lily, daniel, fable, george, lewis |
es Spanish | dora | dora, alex, santa |
fr French | siwis | siwis |
hi Hindi | alpha | alpha, beta, omega, psi |
it Italian | sara | sara, nicola |
pt Portuguese (Brazil) | dora | dora, alex, santa |
- Fast reads 6 languages.
params.voiceis optional; a voice of another language gets422atparams.voice. Fast has no Polish: use Studio for it. - Studio reads 23 languages with one voice each:
ar,da,de,el,en,es,fi,fr,he,hi,it,ja,ko,ms,nl,no,pl,pt,ru,sv,sw,tr,zh. - The text needs at least 3 characters on Fast and 10 on Studio, and at most 200,000 per job. Long texts are read in parts and joined into one MP3.
- Text with control characters, or parts with no words to read, gets
422atinput.textbefore anything is charged. - The job’s
inputshows the length and a hash of the text, not the text.
Upscale
- Input: an MP4 or MOV clip as
video_urlorupload_id, or a video job asjob_id. Up to 10 seconds, at most 1344 px on the longer side and 1344×768 pixels in all. - Clips faster than 30 frames a second are brought to 30 first.
- The output is an MP4 with each side times
scale(2 or 4). The length comes from the file, never from a setting.
The listed prices (Fast 5 or 20, Studio 30 or 110) cover a clip up to 576×1024 and 10 seconds at 24 fps, like our Fast video. A bigger clip costs in proportion to its pixels times frames, rounded up: credits = list price × (width × height × frames) ÷ (576 × 1024 × 241). Frames are counted at no more than 30 and no fewer than 24 a second.
Example: a 10-second clip of 1344×756 at 30 fps costs 43 credits on Fast 4×. Send the clip to POST /v1/quote with your key to get the exact price first.
curl -X POST https://api.sizzle.tools/v1/quote \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"upscale.fast","params":{"scale":4},"input":{"upload_id":"up_7h2m9q4x1k8c3v6b0n5z"}}'Photo
| Operation | Settings | What you get |
|---|---|---|
photo.cleanup | background: transparent (default) or white | The product cut out. Transparent gives a PNG; white gives a JPEG on pure #FFFFFF (RGB 255, 255, 255), as marketplaces ask for main photos. |
photo.scene | scene: where to put the product, 2 to 200 characters (default a bright minimal studio) | The same product in a new setting, PNG. |
photo.color | color: the new colour, 2 to 40 characters, for example navy blue | The same product in that colour, PNG. |
image.generate | prompt: 1 to 1000 characters; aspect: 1:1 (default), 4:5, 9:16 or 16:9 | A new image: 1024×1024, 896×1120, 720×1280 or 1280×720, PNG. |
- Clean-up size: photos up to 1024 px on the longer side are cut out and upscaled 4×. Photos of 1025 to 2048 px, and photos whose size we cannot read, are first scaled down to fit 1024 px, then cut out and upscaled 4×. Photos over 2048 px are scaled down to 2048 px and cut out without the upscale. The result is never over 4096 px.
- New scene and colour change keep the proportions of your photo, at most 1536 px on the longer side, sides in steps of 16 px.
- Image from text needs no input and is not part of the Ultra allowances.
Music
prompt: your own description of the music, 1 to 300 characters, for examplewarm acoustic guitar, slow. When you send it,moodis not used.mood:upbeat(default),calm,luxury,lofi,acousticorcinematic. Use it when you do not write aprompt.duration: whole seconds from 10 to 60, default 30. Studio tracks are at least 20 seconds long.vocals:falseby default. Withtrue,lyrics(up to 2000 characters) is required andvocal_languageisen(default) orpl.- Without a video, every job returns three takes,
take-1totake-3, as MP3. - Music for a video: send the video as
input(job_idof a video you made,upload_idorvideo_url, up to 60 seconds). You get one track made to the video's length (durationis not used) and the video with the music mixed in as the main result (labelvideo), plus the track (music). The price stays 5 or 15 credits. - A
music.fastjob counts as one track in the Ultra allowance.music.studiois not part of it and is paid with credits.
curl -X POST https://api.sizzle.tools/v1/jobs \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: spring-promo-music" \
-d '{"operation":"music.fast","params":{"mood":"acoustic","duration":30}}'curl -X POST https://api.sizzle.tools/v1/jobs \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-d '{"operation":"music.fast","params":{"prompt":"warm acoustic guitar, slow"},"input":{"job_id":"job_k3x9q2m7v1c8b4n6z0wd"}}'Try-on
Send the photo of the person as the main input and the garment as input.garment. The result is one PNG preview labelled preview, at most 1536 px on the longer side.
curl -X POST https://api.sizzle.tools/v1/jobs \
-H "Authorization: Bearer $SIZZLE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: tryon-5531" \
-d '{"operation":"tryon","input":{"image_url":"https://example.com/shopper.jpg","garment":{"image_url":"https://example.com/jacket.jpg"}}}'Use only photos of people who agreed to it. Try-on photos are deleted within 24 hours. To delete them sooner, upload them, pass their upload_id and call DELETE /v1/jobs/:id/files when the job has finished.
Still stuck? Write to support@sizzle.tools.