Jobs and operations

Everything the API makes is a job: you send an operation with its settings and input, then collect the files.

The workflow

  1. Upload a file, or use a public https URL (optional: text and music need no file).
  2. Check the price with POST /v1/quote.
  3. Create the job with POST /v1/jobs.
  4. Poll GET /v1/jobs/:id until the status is succeeded or failed.
  5. Download the files from results before they expire.
  6. 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
201 Created. The upload works for 24 hours, on your account only.
{
  "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:

InputUse 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
}
  • credits is what this job would take from your wallet now; list_credits is the full price.
  • covered_by says where the credits would come from: free, allowance, plan, pack or mixed. enough says whether you have them.
  • Without a key you get the list price, with covered_by, enough and balance set to null.
  • For voice, send the text as input.text, or just its length as params.characters.
  • For upscale, send the clip as input with 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

FieldWhat it is
operationRequired. One of the ids in the operations table.
paramsSettings of the operation. Leave a setting out to get its default.
inputThe file or text to work on, see Send the file.
expected_creditsOptional. 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}'
202 Accepted: the credits are reserved and the job is queued. A repeat with the same Idempotency-Key answers 200 with this job.
{
  "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
done

Poll 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

StatusWhat it means
queuedAccepted, credits reserved, waiting to start.
runningBeing made.
succeededDone. The files are in output and results, and the credits stay spent.
failedCould 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_failedThe result could not be made from this input or these settings.
timeoutIt took too long and was stopped.
unavailableGeneration was unavailable for a while. Try again later.
input_unusableThe 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"
}
Result links need no key. They stop working at expires_at.
curl -s "https://api.sizzle.tools/v1/jobs/$JOB" -H "Authorization: Bearer $SIZZLE_KEY" \
  | jq -r .output.url | xargs curl -s -o video.mp4

Every 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: true and url: null. Credits do not change.
  • Inputs you gave as image_url or video_url are not removed by this call; our copies of them go after 24 hours. Upload a file and pass its upload_id if 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.

OperationWhat it makesInputMain settingsCreditsOutput
video.fastVertical video, no soundPhoto, or none with promptduration 5 or 10 (default 5), prompt20 (5 s), 25 (10 s)MP4 576×1024, 24 fps
video.studioLandscape video with its own soundPhoto, or none with promptduration 5 or 10, prompt50 (5 s), 80 (10 s)MP4 1344×768, 24 fps
video.proVideo with the best motionPhoto, or none with promptduration 5 or 10, prompt, aspect 9:16 (default) or 16:9300 (5 s), 600 (10 s)MP4 720×1280 or 1280×720, 24 fps
upscale.fastSharper, bigger clipClip up to 10 sscale 2 (default) or 45 (2×), 20 (4×) up to 576×1024 and 10 s; bigger clips moreMP4, each side times scale
upscale.studioUpscale with extra detailClip up to 10 sscale 2 or 430 (2×), 110 (4×), same ruleMP4, each side times scale
music.fastMusic track, quick sketch, or music for a videoNone, or a video up to 60 sprompt or mood, duration 10 to 60 s (default 30), vocals, lyrics, vocal_language53 MP3 takes; with a video: the video with music plus the MP3
music.studioMusic track, richer mix, or music for a videoNone, or a video up to 60 sSame as Fast15Same as Fast, tracks at least 20 s
voice.fastVoice-over at low costTextlanguage (6, default en), voice5 per 10,000 charactersOne MP3
voice.studioMore natural voice-overTextlanguage (23, default en)30 per 10,000 charactersOne MP3
photo.cleanupBackground removal and 4× upscalePhotobackground transparent (default) or white2PNG with transparency, or JPEG on pure white; up to 4096 px
photo.sceneYour product in a new settingPhotoscene, 2 to 200 characters5PNG up to 1536 px, same proportions
photo.colorYour product in another colourPhotocolor, 2 to 40 characters (required)5PNG up to 1536 px, same proportions
tryonThe person wearing the garmentPerson photo plus garment photoNone8PNG preview up to 1536 px
image.generateNew image from a descriptionNoneprompt 1 to 1000 characters (required), aspect3PNG 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. prompt is then an optional hint for the motion.
  • From text: send no input and describe the video in params.prompt (1 to 1000 characters after trimming). Without a photo and without a prompt you get 422 at params.prompt. The price and size are the same as from a photo.
  • duration is 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.fast or music.studio with the video as input (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'
One entry of the list. Studio entries have only code and name.
[
  {
    "code": "fr",
    "name": { "en": "French", "pl": "francuski" },
    "default_voice": "siwis",
    "voices": [{ "id": "siwis", "name": "Siwis", "gender": "female", "locale": "fr-FR" }]
  }
]
Fast languageDefault voiceVoices
en EnglishskyUS: 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 Spanishdoradora, alex, santa
fr Frenchsiwissiwis
hi Hindialphaalpha, beta, omega, psi
it Italiansarasara, nicola
pt Portuguese (Brazil)doradora, alex, santa
  • Fast reads 6 languages. params.voice is optional; a voice of another language gets 422 at params.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 422 at input.text before anything is charged.
  • The job’s input shows the length and a hash of the text, not the text.

Upscale

  • Input: an MP4 or MOV clip as video_url or upload_id, or a video job as job_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

OperationSettingsWhat you get
photo.cleanupbackground: transparent (default) or whiteThe 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.scenescene: where to put the product, 2 to 200 characters (default a bright minimal studio)The same product in a new setting, PNG.
photo.colorcolor: the new colour, 2 to 40 characters, for example navy blueThe same product in that colour, PNG.
image.generateprompt: 1 to 1000 characters; aspect: 1:1 (default), 4:5, 9:16 or 16:9A 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 example warm acoustic guitar, slow. When you send it, mood is not used.
  • mood: upbeat (default), calm, luxury, lofi, acoustic or cinematic. Use it when you do not write a prompt.
  • duration: whole seconds from 10 to 60, default 30. Studio tracks are at least 20 seconds long.
  • vocals: false by default. With true, lyrics (up to 2000 characters) is required and vocal_language is en (default) or pl.
  • Without a video, every job returns three takes, take-1 to take-3, as MP3.
  • Music for a video: send the video as input (job_id of a video you made, upload_id or video_url, up to 60 seconds). You get one track made to the video's length (duration is not used) and the video with the music mixed in as the main result (label video), plus the track (music). The price stays 5 or 15 credits.
  • A music.fast job counts as one track in the Ultra allowance. music.studio is 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}}'
Music for a video you made
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.