{"openapi":"3.1.0","info":{"title":"StrikeFree API","version":"2.0.0","summary":"Replace the copyrighted music in a video with music you can use. Keep everything else.","description":"Upload a video that carries music you don't own. StrikeFree finds every music cue, separates it from the speech,\nidentifies the song, generates a new instrumental soundalike and lays it under the\nspeech following the original mix, so the editor's ducking carries over. Cues that cannot be matched with enough\nconfidence are removed instead. Every job returns the new video, the final mix, the stems and a **cue sheet**:\nwhat played, what plays now, how sure we are. `music: remove` skips the replacement and only takes the music out.\n\n**One flow:** `POST /v1/jobs` → poll `GET /v1/jobs/{id}?wait=25` (or SSE, or a webhook) → download `outputs[].url`.\n\n**Sending the video.** Three ways, one endpoint:\n- `multipart/form-data` with field `file`: one request, files up to 50 MB.\n- JSON `{\"upload\": {\"filename\", \"bytes\"}}` for anything bigger (up to 4 GiB): the job is created in state `uploading`\n  with `upload.part_size` (25 MiB) and `upload.parts`; send each part with `PUT /v1/jobs/{id}/parts/{n}` (raw bytes,\n  every part exactly `part_size` except the last), then `POST /v1/jobs/{id}/parts/complete`. The job turns `queued`.\n- JSON `{\"source_url\": \"https://…\"}`: a direct link the worker downloads itself (presigned S3/GCS links work).\n\n**Auth:** `Authorization: Bearer sf_live_…` (or `X-API-Key`). Create keys in the dashboard.\nDashboard sessions use the same header with a Clerk session token.\n\n**Errors:** JSON `{\"error\": {\"type\", \"code\", \"message\", \"param?\"}}`. Types: `invalid_request`, `authentication`,\n`permission`, `not_found`, `conflict`, `insufficient_credits`, `payload_too_large`, `server`.\n\n**Credits:** the billing unit is the credit. **1 credit = 1 song generated and placed in your video.** A song\nthat comes back later in the same video is generated once and costs one credit. Cues that are only removed,\nfailed jobs and canceled jobs cost nothing. A job holds up to `max_songs` credits while it runs and gives back\nwhat it did not use when it finishes. `GET /v1/account` has the balance, `GET /v1/account/meter` the usage.\nNew accounts get 5 free credits. Credits are bought through Stripe Checkout (`POST /v1/account/billing/checkout`).\n\n**Waiting.** `GET /v1/jobs/{id}?wait=N` holds the request for at most 25 s (larger values are accepted and capped),\nso loop until the status is `done`, `failed` or `canceled`. `GET /v1/jobs/{id}/events` (SSE) closes after 50 s;\nreconnect or fall back to `?wait=`. Jobs take minutes.\n\n**For agents:** `/llms.txt` has a one-page guide. An MCP server is at `POST /mcp` (streamable HTTP, JSON responses,\nsame Bearer key; `submit_job` takes a `source_url`). Pass `Idempotency-Key` on job creation so retries never create\nduplicates.\n\n**Worker protocol:** the `worker` tag documents `/v1/worker/*`, what the GPU box speaks. It needs the worker token,\nnot a customer key.\n","contact":{"name":"StrikeFree","url":"https://strikefree.video"},"license":{"name":"Proprietary","url":"https://strikefree.video/legal/terms"}},"servers":[{"url":"https://api.strikefree.video","description":"production"},{"url":"http://localhost:8787","description":"local (`cd edge && pnpm dev`)"}],"tags":[{"name":"jobs","description":"Create a job, upload its video, follow it, fetch outputs."},{"name":"account","description":"Balance, usage, API keys, webhook settings, billing (Stripe)."},{"name":"meta","description":"Health, machine-readable docs, MCP, Stripe webhook receiver."},{"name":"worker","description":"The GPU worker's side of the API (`python -m cleancc worker`). Authenticated with the shared worker token\n(`Authorization: Bearer <WORKER_TOKEN>`); customer credentials are refused. The worker claims a job, pulls its\ninput (or fetches `source_url` itself), reports progress, pushes outputs into storage and finishes. The finish\ncall bills the credits and queues the customer webhook atomically.\n"}],"security":[{"bearer":[]},{"apiKey":[]}],"paths":{"/":{"get":{"tags":["meta"],"security":[],"summary":"Where things are","operationId":"root","responses":{"200":{"description":"Links to the docs, this document, the agent guide and the MCP endpoint.","content":{"application/json":{"schema":{"type":"object","required":["name","docs","openapi","llms","mcp"],"properties":{"name":{"type":"string","const":"StrikeFree API"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"llms":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"}}}}}}}}},"/healthz":{"get":{"tags":["meta"],"security":[],"summary":"Health","operationId":"health","responses":{"200":{"description":"OK (`ok` and `db` true)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"503":{"description":"The database did not answer (`ok` false)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/openapi.json":{"get":{"tags":["meta"],"security":[],"summary":"This document (JSON)","operationId":"openapiJson","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/openapi.yaml":{"get":{"tags":["meta"],"security":[],"summary":"This document (YAML)","operationId":"openapiYaml","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/yaml":{"schema":{"type":"string"}}}}}}},"/llms.txt":{"get":{"tags":["meta"],"security":[],"summary":"One-page guide for LLM agents","operationId":"llmsTxt","responses":{"200":{"description":"Plain text","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/mcp":{"post":{"tags":["meta"],"summary":"MCP server (streamable HTTP, JSON responses)","operationId":"mcp","description":"Stateless JSON-RPC 2.0 over POST. Methods: `initialize`, `ping`, `tools/list`, `tools/call`; `notifications/*`\nare accepted with `202` and no body. Batches (JSON arrays) are answered as arrays. `tools/call` needs the same\n`Authorization: Bearer sf_live_…` (or `X-API-Key`) a REST call would; each tool loops back into the REST routes,\nso validation, billing and errors are identical.\n\nTools: `submit_job` (`source_url` required; `music`, `keep`, `min_similarity`, `max_songs`, `duck_db`, `name`,\n`metadata`, `webhook_url`, `idempotency_key`), `get_job` (`id`, `wait_s` ≤ 300: the server loops `?wait=25`\nfor you), `list_jobs` (`status`, `limit`), `cancel_job` (`id`), `get_account`. Results carry a one-line `text`\nsummary and the REST JSON in `structuredContent`.\n\n`GET /mcp` answers `405` (no SSE stream: this server speaks JSON only). There is no local stdio binary; the\nremote endpoint is the MCP server.\n","security":[{"bearer":[]},{"apiKey":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["integer","string","null"]},"method":{"type":"string","examples":["initialize","tools/list","tools/call"]},"params":{"type":"object","additionalProperties":true}}},"examples":{"call":{"value":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"submit_job","arguments":{"source_url":"https://example.com/ep12.mp4","music":"replace"}}}}}}}},"responses":{"200":{"description":"JSON-RPC response (`result` or `error`)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"Notification accepted, no body"},"400":{"description":"Not JSON","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/jobs":{"post":{"tags":["jobs"],"summary":"Create a job","operationId":"createJob","description":"Three request shapes, one endpoint:\n\n1. **`multipart/form-data`** with the video in field `file` (`video` is a legacy alias) and the options as form\n   fields. One request; the file must be ≤ 50 MB (`413 file_too_large` above). The job starts `queued`.\n2. **JSON with `upload`** `{\"filename\", \"bytes\"}` (and optional `content_type`) for files up to 4 GiB. Returns\n   `202` with `status: uploading` and an `upload` block: `part_size` (26214400 = 25 MiB), `parts` and\n   `upload_id`. Send the bytes with `PUT /v1/jobs/{id}/parts/{n}` for n = 1…parts (every part exactly\n   `part_size` bytes except the last, which carries the remainder), then `POST /v1/jobs/{id}/parts/complete`\n   with the returned etags. The job turns `queued`. An upload with no completion for 24 h is canceled\n   (`error.code` `upload_abandoned`) and its hold released.\n3. **JSON with `source_url`**: a direct http(s) link (≤ 4 GiB). The job starts `queued`; the worker downloads\n   the URL when it picks the job up. Links to private or local addresses are refused at that point\n   (`source_fetch_failed`). Optional `filename` names the input when the URL has none.\n\n`upload` and `source_url` together are rejected (`ambiguous_input`).\n\nRequires at least one available credit (`credits_available` on the account). The job places a **hold** of\n`min(max_songs, credits_available)` credits and never generates more songs than that; it is billed when it\nfinishes: one credit per song generated and placed (`credits_billed`), the rest of the hold is released.\nFailed and canceled jobs are free. `music: remove` jobs generate nothing and cost nothing.\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The video (mp4, mov, mkv, webm, …), ≤ 50 MB in this shape. `video` is accepted as a legacy alias."},"music":{"$ref":"#/components/schemas/Music"},"keep":{"$ref":"#/components/schemas/Keep"},"min_similarity":{"$ref":"#/components/schemas/MinSimilarity"},"duck_db":{"$ref":"#/components/schemas/DuckDb"},"max_songs":{"$ref":"#/components/schemas/MaxSongs"},"name":{"type":"string","maxLength":200,"description":"Your label for the job."},"metadata":{"type":"string","description":"JSON object (as a string), ≤ 4 KB. Returned untouched."},"webhook_url":{"type":"string","format":"uri","description":"Overrides the account default."}}},"encoding":{"file":{"contentType":"video/*, audio/*, application/octet-stream"}}},"application/json":{"schema":{"type":"object","description":"Exactly one of `upload` or `source_url`.","properties":{"upload":{"type":"object","required":["bytes"],"description":"Declare a file you will send in parts.","properties":{"filename":{"type":"string","description":"Original name; its extension picks the stored type (`.mp4`, `.mov`, …)."},"bytes":{"type":"integer","minimum":1,"maximum":4294967296,"description":"Exact size of the file."}}},"content_type":{"type":"string","description":"MIME type of the file, used when `upload.filename` has no extension."},"source_url":{"type":"string","format":"uri","maxLength":4096,"description":"Direct http(s) link to the video. Presigned S3/GCS links work. Fetched by the worker when the job starts."},"filename":{"type":"string","description":"Optional name when `source_url` has none."},"music":{"$ref":"#/components/schemas/Music"},"keep":{"$ref":"#/components/schemas/Keep"},"min_similarity":{"$ref":"#/components/schemas/MinSimilarity"},"duck_db":{"$ref":"#/components/schemas/DuckDb"},"max_songs":{"$ref":"#/components/schemas/MaxSongs"},"name":{"type":"string","maxLength":200},"metadata":{"type":"object","additionalProperties":true,"description":"≤ 4 KB. Returned untouched."},"webhook_url":{"type":"string","format":"uri"}}},"examples":{"inParts":{"summary":"Large file, sent in parts afterwards","value":{"upload":{"filename":"ep12.mp4","bytes":734003200},"music":"replace","name":"Episode 12"}},"fromUrl":{"summary":"Direct link","value":{"source_url":"https://bucket.s3.amazonaws.com/ep12.mp4?X-Amz-Signature=abc123","music":"replace","keep":"speech_fx","name":"Episode 12","metadata":{"show":"morfi","ep":12}}}}}}},"responses":{"200":{"description":"Same `Idempotency-Key` seen before; the existing job is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"202":{"description":"Job accepted. `status` is `uploading` (JSON `upload`, with the `upload` block) or `queued` (multipart file, `source_url`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"},"examples":{"uploading":{"value":{"object":"job","id":"4fbf3d4a-1b2c-4d5e-8f90-123456789abc","status":"uploading","cancel_requested":false,"music":"replace","keep":"speech_fx","min_similarity":0.25,"duck_db":-12,"name":"Episode 12","metadata":{},"input":{"filename":"ep12.mp4","bytes":734003200,"duration_s":null},"progress":{"step":null,"done":[],"elapsed_s":0,"percent":0},"result":null,"error":null,"max_songs":60,"credits_billed":null,"webhook_url":null,"created_at":"2026-11-18T02:14:09.120Z","started_at":null,"finished_at":null,"expires_at":null,"upload":{"part_size":26214400,"parts":28,"upload_id":"2~abc…"}}}}}}},"400":{"description":"Invalid input (`error.param` names the field). Codes include invalid_music, invalid_keep, invalid_min_similarity, invalid_duck_db, invalid_max_songs, invalid_name, invalid_metadata, metadata_too_large, invalid_webhook_url, invalid_idempotency_key, missing_input, ambiguous_input, invalid_upload, invalid_source_url, missing_file, multiple_files, empty_file, unsupported_content_type, invalid_json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"No credit is available to hold (balance used up, or all of it held by jobs in progress). `error.type` is `insufficient_credits`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"`file_too_large`: a one-shot multipart body over 50 MB (use `upload`), or `upload.bytes` over 4 GiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["jobs"],"summary":"List jobs","operationId":"listJobs","description":"Newest first. Cursor pagination.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`next_cursor` from the previous page."},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/Status"}},{"name":"include_deleted","in":"query","schema":{"type":"string","enum":["1"]},"description":"Also list jobs you deleted (their files are gone)."}],"responses":{"200":{"description":"A page of jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/jobs/{id}":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"get":{"tags":["jobs"],"summary":"Get a job","operationId":"getJob","description":"With `wait`, the server holds the request and returns as soon as the job reaches `done`, `failed` or\n`canceled` (long-poll). The wait is capped at **25 s** server-side whatever you ask for; loop until the status\nis terminal. While the job is `uploading` the response carries the `upload` block.\n","parameters":[{"name":"wait","in":"query","schema":{"type":"integer","minimum":0,"maximum":300,"default":0},"description":"Seconds to wait for a terminal state. Values above 25 are accepted and capped at 25."}],"responses":{"200":{"description":"The job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["jobs"],"summary":"Delete a job and its files","operationId":"deleteJob","description":"Removes input and outputs from storage. The job stays in your history as `deleted`. Uploading and queued jobs are canceled (free); a running job gets `cancel_requested` and stops at its next step.","responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/jobs/{id}/parts/{n}":{"parameters":[{"$ref":"#/components/parameters/JobId"},{"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Part number, 1-based, up to `upload.parts`."}],"put":{"tags":["jobs"],"summary":"Upload one part of the video","operationId":"uploadPart","description":"Raw bytes of part `n` of a job created with `upload`. `Content-Length` must be exactly `upload.part_size`\n(26214400) for every part but the last, and `bytes − (parts − 1) × part_size` for the last one; anything else\nis `400 part_size`. Parts may be sent in any order and in parallel; a part can be re-sent (the last write\nwins). Keep the returned `etag` for `parts/complete`.\n","requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Part stored","content":{"application/json":{"schema":{"type":"object","required":["part","etag"],"properties":{"part":{"type":"integer"},"etag":{"type":"string"}}}}}},"400":{"description":"`invalid_part` (n out of range) or `part_size` (wrong `Content-Length`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`not_uploading`: the job is not in state `uploading` (already completed, canceled or deleted).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/jobs/{id}/parts/complete":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"post":{"tags":["jobs"],"summary":"Finish the parts upload","operationId":"completeUpload","description":"Lists every part with its etag. The parts are assembled into the input and the job turns `queued`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["parts"],"properties":{"parts":{"type":"array","minItems":1,"items":{"type":"object","required":["part","etag"],"properties":{"part":{"type":"integer","minimum":1},"etag":{"type":"string"}}}}}},"examples":{"two":{"value":{"parts":[{"part":1,"etag":"a1b2…"},{"part":2,"etag":"c3d4…"}]}}}}}},"responses":{"200":{"description":"The job, now `queued`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"`invalid_parts` (wrong count or shape) or `upload_incomplete` (a part is missing or an etag does not match).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`not_uploading`: the job is not in state `uploading`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/jobs/{id}/cancel":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"post":{"tags":["jobs"],"summary":"Cancel a job","operationId":"cancelJob","description":"Uploading and queued jobs cancel immediately. Running jobs stop at the next step boundary (`cancel_requested` is set). Terminal jobs return `409`.","responses":{"200":{"description":"The job: status `canceled`, or still `running` with `cancel_requested` set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/jobs/{id}/events":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"get":{"tags":["jobs"],"summary":"Follow a job (SSE)","operationId":"jobEvents","description":"`text/event-stream`. Events: `progress` (on every change), then one of `done`, `failed`, `canceled`, after which\nthe stream closes. Each `data:` line is the full Job JSON. A `: keepalive` comment is sent every 15 s.\nThe stream also closes after **50 s** whatever the state: reconnect, or fall back to `GET /v1/jobs/{id}?wait=25`.\n","responses":{"200":{"description":"Event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/jobs/{id}/outputs/{name}":{"parameters":[{"$ref":"#/components/parameters/JobId"},{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"One of `outputs[].name`, e.g. `video.mp4`."}],"get":{"tags":["jobs"],"summary":"Download an output","operationId":"getOutput","description":"Streams the file from storage. Accepts the normal `Authorization` header **or** the pre-signed `sig`/`exp`\nquery pair that `outputs[].url` already includes (valid 24 h) so links can be opened in a browser or handed to\nanother system. Supports `Range` (`206`, `Content-Range`); sends `ETag`, `Last-Modified`, `Accept-Ranges`.\n","security":[{"bearer":[]},{"apiKey":[]},{}],"parameters":[{"name":"sig","in":"query","schema":{"type":"string"}},{"name":"exp","in":"query","schema":{"type":"integer"},"description":"Unix seconds."},{"name":"download","in":"query","schema":{"type":"string","enum":["1"]},"description":"Adds `Content-Disposition: attachment` with a friendly filename (`<job name>-<output>`)."}],"responses":{"200":{"description":"The file","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Partial content","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing credentials, or `invalid_signature`: the link is invalid or expired (fetch the job again for a fresh one).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such job or output, job deleted, or job not `done` yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"`outputs_expired`: outputs were deleted after the retention period (7 days, 30 on Studio and Enterprise)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/account":{"get":{"tags":["account"],"summary":"Account, plan and balance","operationId":"getAccount","responses":{"200":{"description":"The account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"patch":{"tags":["account"],"summary":"Update settings","operationId":"updateAccount","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_url":{"type":["string","null"],"format":"uri","description":"Default webhook for new jobs. `null` clears it."},"default_keep":{"$ref":"#/components/schemas/Keep"}}}}}},"responses":{"200":{"description":"The account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/account/usage":{"get":{"tags":["account"],"summary":"Credit ledger","operationId":"listUsage","description":"Every grant, purchase and charge, newest first. Job rows are negative: one credit per song generated.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of ledger entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/account/keys":{"get":{"tags":["account"],"summary":"List API keys","operationId":"listKeys","description":"Secrets are never returned after creation; only the prefix.","responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["account"],"summary":"Create an API key","operationId":"createKey","description":"**Session only** (dashboard). An API key cannot mint keys. The `secret` is shown once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80}}}}}},"responses":{"201":{"description":"Key with secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/account/keys/{keyId}":{"delete":{"tags":["account"],"summary":"Revoke an API key","operationId":"revokeKey","description":"**Session only.** Immediate; in-flight requests with the key fail with 401.","parameters":[{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Revoked"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/account/webhook-secret":{"post":{"tags":["account"],"summary":"Rotate the webhook signing secret","operationId":"rotateWebhookSecret","description":"**Session only.** Returns the new secret once. Old signatures stop validating immediately.","responses":{"200":{"description":"New secret","content":{"application/json":{"schema":{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","examples":["whsec_9f1c…"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/account/meter":{"get":{"tags":["account"],"summary":"Usage meter","operationId":"getMeter","description":"Where the balance stands (balance, holds, available) and what the last `days` days used, one row per UTC day (zero-filled, oldest first).","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30}}],"responses":{"200":{"description":"The meter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Meter"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/account/billing":{"get":{"tags":["account"],"summary":"Catalog and subscription","operationId":"getBilling","description":"What can be bought (Stripe price ids to pass to `checkout`), the current subscription, and `portal_url`: a\nfresh Stripe customer-portal link when the account already has a Stripe customer (`null` otherwise, and on\nservers running without Stripe, where `mock` is true).\n","responses":{"200":{"description":"Billing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Billing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/account/billing/checkout":{"post":{"tags":["account"],"summary":"Start a Stripe Checkout session","operationId":"createCheckout","description":"Creates a hosted Stripe Checkout session for one catalog price (`payment` mode for packs, `subscription` for\nStudio) and returns its `url`. Navigate the browser there. Stripe sends the customer back to\n`<web>/app/billing?checkout=success&session_id=…` or `…?checkout=canceled`; the credits land when the\n`checkout.session.completed` webhook arrives, usually within seconds. An optional `X-User-Email` header\nprefills the email for accounts without a Stripe customer yet.\n","parameters":[{"name":"X-User-Email","in":"header","required":false,"schema":{"type":"string","format":"email"},"description":"Prefills Checkout for first-time buyers."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["price_id"],"properties":{"price_id":{"type":"string","description":"A `prices[].id` from `GET /v1/account/billing`."},"locale":{"type":"string","pattern":"^[a-z]{2}(-[A-Z]{2})?$","description":"Checkout language, e.g. `es`; default `auto`."}}}}}},"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","required":["url","session_id"],"properties":{"url":{"type":"string","format":"uri","description":"Hosted Checkout page."},"session_id":{"type":"string","examples":["cs_live_a1…"]}}}}}},"400":{"description":"`unknown_price`: not in the catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`checkout_unavailable`: this server runs without Stripe (`BILLING_MOCK=1`); use `mock-purchase`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/account/billing/portal":{"post":{"tags":["account"],"summary":"Open the Stripe customer portal","operationId":"createPortal","description":"Returns a fresh customer-portal link (invoices, payment method, cancel the subscription). The portal returns to `<web>/app/billing`.","responses":{"200":{"description":"Portal session created","content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"`no_customer` (nothing bought yet) or `portal_unavailable` (server without Stripe).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/account/billing/mock-purchase":{"post":{"tags":["account"],"summary":"Dev only — credit a price without Stripe","operationId":"mockPurchase","description":"Exists only when the server runs without Stripe (`BILLING_MOCK=1`, or no `STRIPE_SECRET_KEY`). Returns `404 route_not_found` otherwise. The mock catalog has `price_mock_pack_20`, `price_mock_pack_100`, `price_mock_pack_500` and `price_mock_studio`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["price_id"],"properties":{"price_id":{"type":"string"}}}}}},"responses":{"200":{"description":"The account after crediting","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/webhooks/stripe":{"post":{"tags":["meta"],"security":[],"summary":"Stripe webhook receiver","operationId":"stripeWebhook","description":"Verifies `Stripe-Signature` (HMAC-SHA256 of `t.body`, 5 min tolerance) against `STRIPE_WEBHOOK_SECRET`.\nHandles `checkout.session.completed` (packs: credits; subscriptions: plan + customer), `invoice.paid`\n(monthly credit grant, renewal date), `customer.subscription.updated` / `.deleted` / `.paused` / `.resumed`\n(plan and status). Idempotent twice over: by Stripe event id (a replayed event answers `duplicate: true`) and\nby checkout session / invoice id in the ledger (the same purchase is never credited twice).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A Stripe event."}}}},"responses":{"200":{"description":"Processed or already seen","content":{"application/json":{"schema":{"type":"object","required":["received","duplicate"],"properties":{"received":{"type":"boolean","const":true},"duplicate":{"type":"boolean"},"outcome":{"type":"string","description":"What was done, e.g. `credited 100`, `subscription active`, `ignored`."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"`invalid_signature`, or `webhooks_disabled` when the server has no `STRIPE_WEBHOOK_SECRET`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/worker/claim":{"post":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Claim the next job","operationId":"workerClaim","description":"Atomically moves the oldest highest-priority `queued` job to `running` (Studio and Enterprise jobs first) and returns it, or `204` when the queue is empty. Poll every few seconds.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"worker":{"type":"string","maxLength":120,"description":"Who is claiming, e.g. `vast-1:4312`; recorded on the job."}}}}}},"responses":{"200":{"description":"A job to run","content":{"application/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/WorkerJob"}}}}}},"204":{"description":"Nothing queued"},"401":{"$ref":"#/components/responses/WorkerUnauthorized"}}}},"/v1/worker/jobs/{id}":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"get":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Look at a job","operationId":"workerGetJob","responses":{"200":{"description":"The worker view and the current status","content":{"application/json":{"schema":{"type":"object","required":["job","status"],"properties":{"job":{"$ref":"#/components/schemas/WorkerJob"},"status":{"$ref":"#/components/schemas/Status"}}}}}},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/worker/jobs/{id}/input":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"get":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Download the input","operationId":"workerGetInput","description":"Streams the uploaded video from storage; `Range` supported (`206`) so an interrupted download resumes. Jobs created with `source_url` have no stored input (`404 input_not_found`); fetch the URL yourself and refuse private or local hosts.","responses":{"200":{"description":"The input","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"206":{"description":"Partial content","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/worker/jobs/{id}/progress":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"post":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Report progress, learn about cancellation","operationId":"workerProgress","description":"Stores `progress` (only while the job is `running`), optionally `duration_s` and `input_bytes` once the file has been read. Always answers the current status and `cancel_requested`; the worker polls it between sub-steps and stops when it is true.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"step":{"type":["string","null"],"description":"Current step: extract · detect · separate · identify · match · render."},"done":{"type":"array","items":{"type":"string"},"description":"Steps finished so far."},"elapsed_s":{"type":"number"},"duration_s":{"type":"number","description":"Length of the input in seconds."},"input_bytes":{"type":"integer","description":"Size of the input (for `source_url` jobs, unknown until fetched)."}}}}}},"responses":{"200":{"description":"Current state","content":{"application/json":{"schema":{"type":"object","required":["status","cancel_requested"],"properties":{"status":{"$ref":"#/components/schemas/Status"},"cancel_requested":{"type":"boolean","description":"True when the customer canceled or deleted the job; finish with `canceled`."}}}}}},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/worker/jobs/{id}/outputs/{name}":{"parameters":[{"$ref":"#/components/parameters/JobId"},{"$ref":"#/components/parameters/OutputName"}],"post":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Store an output (one request)","operationId":"workerPutOutput","description":"Raw body, `Content-Length` required, ≤ 50 MB (`413 output_too_large` above; use the multipart route). `Content-Type` is stored when sent, otherwise derived from the name.","requestBody":{"required":true,"content":{"*/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutputMeta"}}}},"400":{"description":"`invalid_output_name` or `length_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"`output_too_large`: over 50 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/worker/jobs/{id}/outputs/{name}/multipart":{"parameters":[{"$ref":"#/components/parameters/JobId"},{"$ref":"#/components/parameters/OutputName"}],"post":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Start a multipart output upload","operationId":"workerStartOutputMultipart","description":"For outputs over 50 MB. Returns an `upload_id`; then `PUT …/parts/{n}?upload_id=` (5 MiB ≤ part ≤ 50 MB, the worker uses 25 MiB) and `POST …/complete`. `Content-Type` on this request is stored on the object.","responses":{"200":{"description":"Upload opened","content":{"application/json":{"schema":{"type":"object","required":["upload_id","part_size_min","part_size_max"],"properties":{"upload_id":{"type":"string"},"part_size_min":{"type":"integer","const":5242880},"part_size_max":{"type":"integer","const":52428800}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/worker/jobs/{id}/outputs/{name}/parts/{n}":{"parameters":[{"$ref":"#/components/parameters/JobId"},{"$ref":"#/components/parameters/OutputName"},{"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":10000}},{"name":"upload_id","in":"query","required":true,"schema":{"type":"string"}}],"put":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Upload one part of an output","operationId":"workerPutOutputPart","description":"Raw body with `Content-Length`, ≤ 50 MB (`413 part_too_large`). Keep the `etag`.","requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Part stored","content":{"application/json":{"schema":{"type":"object","required":["part","etag"],"properties":{"part":{"type":"integer"},"etag":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"`part_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/worker/jobs/{id}/outputs/{name}/complete":{"parameters":[{"$ref":"#/components/parameters/JobId"},{"$ref":"#/components/parameters/OutputName"}],"post":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Finish a multipart output upload","operationId":"workerCompleteOutputMultipart","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["upload_id","parts"],"properties":{"upload_id":{"type":"string"},"parts":{"type":"array","minItems":1,"items":{"type":"object","required":["part","etag"],"properties":{"part":{"type":"integer","minimum":1},"etag":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutputMeta"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/worker/jobs/{id}/finish":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"post":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Finish a job (bills and notifies atomically)","operationId":"workerFinish","description":"Moves the job to `done`, `failed` or `canceled` and, in the same database batch: counts the songs in\n`result.cues` (distinct `replacement.track_id` among replaced cues), bills `min(songs, max_songs)` credits\n(`CREDITS_REMOVE_JOB`, 0, for `music: remove`; nothing for `failed` / `canceled`), writes the ledger row, sets\n`expires_at` (7 days, 30 on Studio and Enterprise) and queues the customer webhook. When `outputs` is omitted\non `done`, the objects under the job's output prefix are listed and recorded. `progress` defaults to the stored\nprogress with `step: done`. A job already terminal answers `409 already_finished`; a replayed finish never\ndouble-charges.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["done","failed","canceled"]},"error":{"type":"string","maxLength":4000,"description":"`<code>: <message>`; known codes source_fetch_failed, processing_failed, replace_unavailable, canceled, worker_lost become `error.code` on the job."},"result":{"$ref":"#/components/schemas/Result"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/OutputMeta"}},"progress":{"$ref":"#/components/schemas/Progress"}}}}}},"responses":{"200":{"description":"Finished","content":{"application/json":{"schema":{"type":"object","required":["job","credits_billed","songs"],"properties":{"job":{"$ref":"#/components/schemas/Job"},"credits_billed":{"type":["integer","null"],"description":"Credits charged by this call (`null` for failed / canceled)."},"songs":{"type":"integer","description":"Songs counted in the result."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`already_finished`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/worker/jobs/{id}/resume":{"parameters":[{"$ref":"#/components/parameters/JobId"}],"post":{"tags":["worker"],"security":[{"workerToken":[]}],"summary":"Take a job over (operator use)","operationId":"workerResume","description":"Puts a `failed`, `running` (lost worker) or `queued` job back into `running` under this worker, clearing its error and billing; `python -m cleancc worker --resume <id>` reuses the steps already on disk. Terminal `done` / `canceled` jobs answer `409 not_resumable`.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"worker":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"The job, running again","content":{"application/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#/components/schemas/WorkerJob"}}}}}},"401":{"$ref":"#/components/responses/WorkerUnauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`not_resumable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{"jobEvent":{"post":{"operationId":"jobEvent","summary":"Job finished","description":"Sent to the job's `webhook_url` (or the account default) when a job reaches `done`, `failed` or `canceled`.\nHeaders: `StrikeFree-Event` (`job.completed` | `job.failed` | `job.canceled`), `StrikeFree-Delivery` (unique id),\n`StrikeFree-Signature: t=<unix>,v1=<hex hmac-sha256(secret, t + \".\" + body)>`, `User-Agent: strikefree-webhooks/1`.\nDelivered within a minute of finishing (a cron runs every minute); on non-2xx or a 10 s timeout it retries at\n1 m, 5 m, 30 m, 2 h and 12 h (5 attempts over ~15 h), then gives up. Reply 2xx fast; fetch outputs afterwards.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer sf_live_…` for API keys, or a Clerk session token from the dashboard. Locally with `AUTH_MOCK=1`: `Bearer mock:<account>`."},"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Same API key, alternative header."},"workerToken":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer <WORKER_TOKEN>`: the one shared secret of the GPU worker (`STRIKEFREE_WORKER_TOKEN` on the box, `WORKER_TOKEN` secret on the API). Only valid under `/v1/worker/`."}},"parameters":{"JobId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"OutputName":{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$"},"description":"Output file name: letters, digits, dot, dash, underscore; e.g. `video.mp4`, `cue_sheet.json`."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Any unique string (≤ 200 chars). Repeating it returns the first job (`200`) instead of creating another."}},"responses":{"BadRequest":{"description":"Invalid input (`error.param` names the field)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"WorkerUnauthorized":{"description":"`invalid_worker_token`: worker token missing or wrong","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Valid credentials, not allowed (e.g. API key used where a session is required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Unknown, deleted, or not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"State does not allow this","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"Health":{"type":"object","required":["ok","db","time"],"properties":{"ok":{"type":"boolean"},"db":{"type":"boolean","description":"The database answered."},"time":{"type":"string","format":"date-time"}}},"Music":{"type":"string","enum":["replace","remove"],"default":"replace","description":"`replace`: swap each music cue for a new instrumental soundalike (one credit per song); cues that cannot be matched are removed. `remove`: take the music out and stop there (no credits)."},"Keep":{"type":"string","enum":["speech_fx","speech"],"default":"speech_fx","description":"What stays from the original mix under the new music. `speech_fx`: speech, crowd, laughter and effects. `speech`: speech only."},"MaxSongs":{"type":"integer","minimum":1,"maximum":1000,"default":60,"description":"The most songs this job may generate, which is the most credits it can cost. The job holds `min(max_songs, credits_available)` credits; cues past the cap are removed instead of replaced (cue `note` says so). Lower it to leave credits free for jobs you run at the same time."},"MinSimilarity":{"type":"number","minimum":0,"maximum":1,"default":0.25,"description":"A cue is replaced only when its best candidate's audio similarity (0–1) reaches this value; otherwise it is removed. Raise it to be stricter."},"DuckDb":{"type":"number","minimum":-60,"maximum":0,"default":-12,"description":"Where music is removed rather than replaced and nobody talks, the original is lowered this much (dB) instead of scrubbed, so a music-only stretch does not fall silent."},"Status":{"type":"string","enum":["uploading","queued","running","done","failed","canceled"],"description":"`uploading` (parts still expected) → `queued` → `running` → `done` | `failed` | `canceled`."},"Upload":{"type":"object","description":"Present while `status` is `uploading`.","required":["part_size","parts","upload_id"],"properties":{"part_size":{"type":"integer","const":26214400,"description":"Bytes per part (25 MiB). Every part but the last must be exactly this size."},"parts":{"type":"integer","description":"Number of parts: `ceil(bytes / part_size)`."},"upload_id":{"type":"string","description":"Storage upload id; informational, the API tracks it for you."}}},"Job":{"type":"object","required":["object","id","status","cancel_requested","music","keep","min_similarity","duck_db","metadata","input","progress","created_at"],"properties":{"object":{"type":"string","const":"job"},"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/Status"},"cancel_requested":{"type":"boolean","description":"A cancel arrived while running; the worker stops at its next step."},"music":{"$ref":"#/components/schemas/Music"},"keep":{"$ref":"#/components/schemas/Keep"},"min_similarity":{"type":"number"},"duck_db":{"type":"number"},"name":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true},"input":{"type":"object","required":["filename","bytes"],"properties":{"filename":{"type":"string"},"bytes":{"type":"integer","description":"`0` for `source_url` jobs until the worker has fetched the file."},"duration_s":{"type":["number","null"],"description":"Known once the worker has read the file."}}},"progress":{"$ref":"#/components/schemas/Progress"},"result":{"oneOf":[{"$ref":"#/components/schemas/Result"},{"type":"null"}]},"outputs":{"type":"array","description":"Present when `done` (empty after expiry).","items":{"$ref":"#/components/schemas/Output"}},"error":{"oneOf":[{"$ref":"#/components/schemas/JobError"},{"type":"null"}]},"max_songs":{"type":["integer","null"],"description":"The job's credit hold: the most songs it may generate. Set at creation to `min(requested max_songs, credits_available)`; `0` for `music: remove`."},"credits_billed":{"type":["integer","null"],"description":"Set when the job is done: songs generated and placed (distinct `replacement.track_id` among the replaced cues), never above `max_songs`. `null` until billed and for failed or canceled jobs."},"webhook_url":{"type":["string","null"]},"upload":{"$ref":"#/components/schemas/Upload"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When outputs are deleted (7 days after finishing; 30 on Studio and Enterprise)."},"deleted_at":{"type":"string","format":"date-time","description":"Only on deleted jobs."}},"examples":[{"object":"job","id":"4fbf3d4a-1b2c-4d5e-8f90-123456789abc","status":"running","cancel_requested":false,"music":"replace","keep":"speech_fx","min_similarity":0.25,"duck_db":-12,"name":"Episode 12","metadata":{"show":"morfi"},"input":{"filename":"ep12.mp4","bytes":734003200,"duration_s":1456.2},"progress":{"step":"identify","done":["extract","detect","separate"],"elapsed_s":310,"percent":50},"result":null,"error":null,"max_songs":60,"credits_billed":null,"webhook_url":null,"created_at":"2026-11-18T02:14:09.120Z","started_at":"2026-11-18T02:14:12.004Z","finished_at":null,"expires_at":null}]},"Progress":{"type":"object","properties":{"step":{"type":["string","null"],"description":"extract · detect · separate · identify · match · render · done"},"done":{"type":"array","items":{"type":"string"}},"elapsed_s":{"type":"number"},"percent":{"type":"integer","minimum":0,"maximum":100,"description":"Estimate from the step weights (extract 5, detect 10, separate 35, identify 10, match 15, render 25)."}}},"Result":{"type":"object","description":"Written by the worker when the job is done. The same rows are delivered as `cue_sheet.json` and `cue_sheet.csv`.","required":["cues"],"properties":{"elapsed_s":{"type":"number"},"music_s":{"type":"number","description":"Seconds of music found in the input."},"replaced_s":{"type":"number","description":"Seconds now covered by replacement music."},"removed_s":{"type":"number","description":"Seconds where the music was removed instead."},"cues":{"type":"array","items":{"$ref":"#/components/schemas/Cue"}}}},"Cue":{"type":"object","description":"One stretch of music in the input and what happened to it. The cue sheet is the list of these.","required":["start","end","action","original","flags"],"properties":{"start":{"type":"number","description":"Seconds into the input."},"end":{"type":"number"},"action":{"type":"string","enum":["replaced","removed"]},"original":{"type":"object","required":["how"],"properties":{"how":{"type":"string","enum":["identified","tagged","detected"],"description":"`identified`: the song was recognised by fingerprint on the separated music stem. `tagged`: not recognised, described by genre / mood / tempo instead. `detected`: found but not analysed (`music: remove`)."},"artist":{"type":["string","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"],"description":"For `tagged` cues, what the music sounds like, e.g. `low-energy slow classical piano, ~70 bpm`."}}},"replacement":{"description":"The track now playing in this cue. `null` when the cue was removed.","oneOf":[{"type":"object","required":["provider","track_id","title","artists","similarity"],"properties":{"provider":{"type":"string","enum":["stable_audio","epidemic_sound"],"description":"`stable_audio`: generated for this cue. `epidemic_sound`: picked from the licensed catalog."},"track_id":{"type":"string"},"title":{"type":"string"},"artists":{"type":"array","items":{"type":"string"}},"genres":{"type":"array","items":{"type":"string"}},"bpm":{"type":["integer","null"]},"url":{"type":["string","null"],"format":"uri","description":"The track's catalog page; `null` for generated tracks."},"prompt":{"type":"string","description":"Generated tracks only: the description the track was generated from (style, instruments, mood, tempo; never an artist or a title)."},"similarity":{"type":"number","description":"Audio similarity between the candidate and the original cue, 0–1. Compare with `min_similarity`."},"looped":{"type":"boolean","description":"True when the track was shorter than the cue and was repeated to fill it."}}},{"type":"null"}]},"level":{"description":"How the replacement was placed. `null` when the cue was removed.","oneOf":[{"type":"object","properties":{"original_db":{"type":"number","description":"Median level of the original music inside the cue (dBFS)."},"gain_db":{"type":"number","description":"Gain applied to the replacement so it sits where the original did."},"range_db":{"type":"number","description":"How much the original moved inside the cue (the editor's ducking). The replacement follows that envelope."}}},{"type":"null"}]},"flags":{"type":"array","items":{"type":"string","enum":["speech_buried","possible_singing"]},"description":"`speech_buried`: music was ≥ 10 dB over the speech; expect damaged voice there. `possible_singing`: someone sings on camera; the cue is never replaced."},"note":{"type":["string","null"],"description":"Why a cue was removed: `similarity 0.07 below 0.25`, `no candidate`, `singing`, `music: remove`."}}},"OutputMeta":{"type":"object","description":"One stored output, as the worker reports it.","required":["name","bytes","content_type"],"properties":{"name":{"type":"string"},"bytes":{"type":"integer"},"content_type":{"type":"string"}}},"Output":{"type":"object","required":["name","bytes","url","content_type"],"properties":{"name":{"type":"string","description":"`video.<ext>` (new soundtrack, picture copied) · `audio.mp3` (the final mix) · `cue_sheet.json` · `cue_sheet.csv` · `speech_fx.mp3` or `speech.mp3` (what was kept, music removed) · `original_music.mp3` (what was taken out) · `replacement_music.mp3` (the new music alone; `music: replace` only) · `music_timeline.csv` (music probability per second)"},"bytes":{"type":"integer"},"content_type":{"type":"string"},"url":{"type":"string","format":"uri","description":"Pre-signed, absolute, valid 24 h. No auth header needed. Fetch the job again for a fresh one."}}},"JobError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["processing_failed","source_fetch_failed","replace_unavailable","canceled","worker_lost","upload_abandoned"]},"message":{"type":"string"}}},"JobList":{"type":"object","required":["object","data","has_more"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"WorkerJob":{"type":"object","description":"What the worker needs to run a job (the customer-facing shape is `Job`).","required":["id","music","keep","min_similarity","duck_db","input_name","input_bytes","source_url","max_songs","priority","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"music":{"$ref":"#/components/schemas/Music"},"keep":{"$ref":"#/components/schemas/Keep"},"min_similarity":{"type":"number"},"duck_db":{"type":"number"},"input_name":{"type":"string","description":"Stored object name, `input.<ext>`; the extension tells the container."},"input_bytes":{"type":"integer"},"source_url":{"type":["string","null"],"description":"When set, there is no stored input; the worker fetches this URL."},"max_songs":{"type":["integer","null"],"description":"Never place more distinct songs than this (the credit hold)."},"priority":{"type":"integer","description":"`1` for Studio and Enterprise accounts."},"created_at":{"type":"string","format":"date-time"}}},"Account":{"type":"object","required":["object","id","plan","credits_balance","credits_held","credits_available","webhook_secret_hint","default_keep","created_at"],"properties":{"object":{"type":"string","const":"account"},"id":{"type":"string","description":"Clerk organization id or user id."},"plan":{"type":"string","enum":["free","studio","enterprise"]},"credits_balance":{"type":"integer","description":"Credits owned. 1 credit = 1 song generated. Never negative: a job cannot be billed more than it holds."},"credits_held":{"type":"integer","description":"Held by jobs that are uploading, queued, running or waiting to be billed (sum of their `max_songs`)."},"credits_available":{"type":"integer","description":"`credits_balance − credits_held`: what a new job can hold. New jobs need at least 1."},"webhook_url":{"type":["string","null"]},"webhook_secret_hint":{"type":"string","description":"Last 4 chars of the signing secret, e.g. `…ab12`."},"default_keep":{"$ref":"#/components/schemas/Keep"},"subscription":{"oneOf":[{"$ref":"#/components/schemas/Subscription"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}}},"Subscription":{"type":"object","properties":{"id":{"type":"string","description":"Stripe subscription id."},"status":{"type":"string","enum":["active","trialing","past_due","paused","canceled"]},"renews_at":{"type":["string","null"],"format":"date-time"}}},"UsageEntry":{"type":"object","required":["id","kind","credits","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["free_grant","purchase","subscription_grant","job","adjustment"]},"credits":{"type":"integer","description":"Positive for grants and purchases, negative for jobs (one per song generated)."},"job_id":{"type":["string","null"],"format":"uuid"},"note":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"UsageList":{"type":"object","required":["object","data","has_more"],"properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageEntry"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"ApiKey":{"type":"object","required":["id","name","prefix","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","examples":["sf_live_7f3a9c1e"]},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"}}},"ApiKeyCreated":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Full key. Shown once."}}}]},"Price":{"type":"object","required":["id","kind","credits","plan"],"properties":{"id":{"type":"string","description":"Stripe price id (`price_…`). Pass to `checkout`."},"kind":{"type":"string","enum":["pack","subscription"]},"credits":{"type":"integer","description":"Credits added per purchase (pack) or per billing period (subscription)."},"plan":{"type":["string","null"],"description":"Plan granted by a subscription price (`studio`); `null` for packs."}}},"Meter":{"type":"object","required":["object","credits_balance","credits_held","credits_available","period_days","credits_used","credits_added","jobs","daily"],"properties":{"object":{"type":"string","const":"meter"},"credits_balance":{"type":"integer"},"credits_held":{"type":"integer"},"credits_available":{"type":"integer"},"period_days":{"type":"integer"},"credits_used":{"type":"integer","description":"Credits charged to jobs in the period (= songs generated)."},"credits_added":{"type":"integer","description":"Grants and purchases in the period."},"jobs":{"type":"integer","description":"Jobs billed in the period, including the ones that cost nothing."},"daily":{"type":"array","items":{"type":"object","required":["date","credits_used","jobs"],"properties":{"date":{"type":"string","format":"date","description":"UTC day."},"credits_used":{"type":"integer"},"jobs":{"type":"integer"}}}}}},"Billing":{"type":"object","required":["plan","prices","subscription","portal_url","mock"],"properties":{"plan":{"type":"string"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"},"description":"Packs first, then subscriptions, cheapest first."},"subscription":{"oneOf":[{"$ref":"#/components/schemas/Subscription"},{"type":"null"}]},"portal_url":{"type":["string","null"],"format":"uri","description":"Stripe customer portal link when the account has a Stripe customer; short-lived, fetch again when needed."},"mock":{"type":"boolean","description":"True when the server runs without Stripe (`mock-purchase` is available, `checkout` is not)."}}},"WebhookEvent":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string","examples":["evt_3f9a1c0d2b7e"]},"type":{"type":"string","enum":["job.completed","job.failed","job.canceled"]},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Job"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string","enum":["invalid_request","authentication","permission","not_found","conflict","rate_limited","insufficient_credits","payload_too_large","server"]},"code":{"type":"string","examples":["invalid_music","missing_file","insufficient_credits","job_not_found","not_uploading","part_size"]},"message":{"type":"string"},"param":{"type":"string","description":"The offending field, when there is one."}}}}}}}}