SeraStudio Fix
SeraStudio Fix generation API
Remake one time range of a video and get the whole video back with that range replaced. The price of the seconds sent is held when the request is accepted.
https://serastudio.app/api/v1/fix/generationsUsage notes
- The key needs the create permission. Keys created in the console have it.
- Upload the video first with Create upload, or use a finished generation of this workspace as the source (
generation_id). The id of an earlier fix works too. - Keep the range to the seconds that are wrong. Estimate fix returns the seconds sent and the price before you create anything.
- On
202the fix is queued andbilling.held_usdis held from the workspace balance. That amount is the charge when it finishes; a failed or canceled fix restores it. - A new fix builds on the newest finished fix of that video. Send
on_versionto build on another one. Only one fix per video runs at a time (409 fix_in_progress). - Fixing the same range of the same version with the same kind again costs 50% of the price, once. The new result keeps every other fix of the current version.
- Send an
Idempotency-Keyheader (1 to 255 ASCII characters). A retry with the same key and body returns the existing generation with200; a different body returns422 idempotency_key_mismatch. - Follow progress with Get generation and
wait_s, or sendwebhook_url. See Webhooks. - The endpoint ignores fields it does not know.
Quick start
curl https://serastudio.app/api/v1/fix/generations \
-H "Authorization: Bearer $SERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fix-2041" \
-d '{"source": {"upload_id": "vid_…"}, "kind": "retouch", "start_s": 8.5, "end_s": 9.9, "source_duration_s": 14, "resolution": "720p", "prompt": "Give the right hand five natural fingers."}'import os, requests
r = requests.post(
"https://serastudio.app/api/v1/fix/generations",
headers={"Authorization": f"Bearer {os.environ['SERA_API_KEY']}", "Content-Type": "application/json", "Idempotency-Key": "fix-2041"},
json={"source": {"upload_id": "vid_…"}, "kind": "retouch", "start_s": 8.5, "end_s": 9.9, "source_duration_s": 14, "resolution": "720p", "prompt": "Give the right hand five natural fingers."},
)
print(r.json()["id"], r.json()["status"])const res = await fetch('https://serastudio.app/api/v1/fix/generations', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SERA_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'fix-2041',
},
body: JSON.stringify({"source": {"upload_id": "vid_…"}, "kind": "retouch", "start_s": 8.5, "end_s": 9.9, "source_duration_s": 14, "resolution": "720p", "prompt": "Give the right hand five natural fingers."}),
});
const fix = await res.json();
console.log(fix.id, fix.status);Input schema
sourceobjectrequiredThe video to fix: {"upload_id": "vid_..."} from Create upload, or {"generation_id": "..."} for a finished generation of this workspace (a Siren generation or an earlier fix).
kindstringrequired"retouch", "swap", "fill". See kinds.
start_snumberrequiredStart of the range in seconds from the beginning of the video.
end_snumberrequiredEnd of the range in seconds. Must be greater than start_s and not past the end of the video.
source_duration_snumberMeasured length of the video in seconds, up to 60. Required when the source is an upload. A finished generation uses its stored length.
promptstringWhat to fix inside the range, in English. Required for retouch, optional for swap and fill.
imagesarrayReference photos, each {"upload_id": "img_..."}. retouch: up to 4; swap: 1 required, up to 4; fill: none.
resolutionstringdefault: "720p"Resolution the range is made at. retouch: "480p", "720p", "1080p"; swap: "720p", "1080p"; fill: "480p", "720p", "1080p" (480p from 2 seconds).
on_versionstringId of a finished fix of this video to build on. Leave it out to build on the newest one.
webhook_urlstringPublic https URL that receives the generation when it finishes. Optional. See Webhooks.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <api-key> |
Idempotency-Key | No | 1 to 255 printable ASCII characters. Same key and body: the same generation comes back with 200. |
Response
A new fix returns 202 with the generation object:
{
"id": "0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70",
"object": "generation",
"model": "fix",
"status": "queued",
"created_at": "2026-11-09T05:11:02.000Z",
"finished_at": null,
"input": {
"source": {
"upload_id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21"
},
"images": [],
"prompt": "Give the right hand five natural fingers.",
"resolution": "720p",
"source_duration_s": 14,
"webhook_url": null
},
"fix": {
"kind": "retouch",
"start_s": 8.5,
"end_s": 9.9,
"window_seconds": 2,
"video_id": "3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21",
"on_version": null,
"retry_discount_pct": 0
},
"progress": {
"stage": "queued",
"percent": 0
},
"output": null,
"output_deleted": false,
"error": null,
"billing": {
"currency": "usd",
"resolution": "720p",
"usd_per_second": 0.175,
"discount_pct": 0,
"held_usd": 0.7,
"charged_usd": null,
"restored_usd": 0,
"settled": false
},
"idempotency_key": "fix-2041"
}When it finishes, output is the whole video with the range replaced and billing.charged_usd equals billing.held_usd:
{
"id": "0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70",
"object": "generation",
"model": "fix",
"status": "succeeded",
"created_at": "2026-11-09T05:11:02.000Z",
"finished_at": "2026-11-09T05:13:36.000Z",
"input": {
"source": {
"upload_id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21"
},
"images": [],
"prompt": "Give the right hand five natural fingers.",
"resolution": "720p",
"source_duration_s": 14,
"webhook_url": null
},
"fix": {
"kind": "retouch",
"start_s": 8.5,
"end_s": 9.9,
"window_seconds": 2,
"video_id": "3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21",
"on_version": null,
"retry_discount_pct": 0
},
"progress": null,
"output": {
"url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70/a1/master.mp4?token=<signed>",
"thumbnail_url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70/a1/thumb.jpg?token=<signed>",
"duration_s": 14,
"url_expires_at": "2026-11-09T06:15:00.000Z",
"retained_until": "2026-11-16T05:13:36.000Z"
},
"output_deleted": false,
"error": null,
"billing": {
"currency": "usd",
"resolution": "720p",
"usd_per_second": 0.175,
"discount_pct": 0,
"held_usd": 0.7,
"charged_usd": 0.7,
"restored_usd": 0,
"settled": true
},
"idempotency_key": "fix-2041"
}fix.kindstringThe kind that was requested.
fix.start_s, fix.end_snumberThe range that is replaced. fill rounds its length to whole seconds.
fix.window_secondsnumberWhole seconds sent to the model and billed.
fix.video_idstringThe video this fix belongs to: the same value for every fix of one video.
fix.on_versionstringThe fix this one was built on, or null when it was built on the untouched source.
fix.retry_discount_pctnumber50 when this request repeated a finished fix of the same range, otherwise 0.
See Get generation for the other fields.
Errors
| Status | Code | When it happens | Retry |
|---|---|---|---|
400 | invalid_json | The body is not a JSON object. | No |
400 | invalid_idempotency_key | The Idempotency-Key header is empty, longer than 255 characters or not printable ASCII. | No |
401 | api_key_missing | No Bearer key was sent in the Authorization header. | No |
401 | api_key_invalid | The key is malformed or unknown. | No |
401 | api_key_revoked | The key was deleted in the console. | No |
401 | api_key_disabled | The key is disabled in the console. | No |
401 | api_key_expired | The key is past its expiration date. | No |
403 | insufficient_scope | The key lacks the create permission. Keys created in the console have it. | No |
403 | workspace_forbidden | The account that owns the workspace is suspended or scheduled for deletion. | No |
402 | insufficient_balance | The price of this fix is larger than the workspace balance. Nothing was created. | No |
404 | not_found | An upload id or the source generation does not exist in this workspace, or no file was put to the upload address. | No |
409 | source_not_ready | The source generation has not finished, failed, or its output was deleted. | No |
409 | version_unavailable | on_version is not a finished fix of this video, or its output is no longer stored. | No |
409 | fix_in_progress | Another fix of the same video is queued or in progress. | Yes |
422 | invalid_parameter | A field is missing or has the wrong type or value. error.param names the field. | No |
422 | invalid_parameter | end_s is past the end of the source, the range is empty, or it is longer than the kind remakes at a time. | No |
422 | source_too_short | The whole source is shorter than the seconds this kind sends to the model. | No |
422 | source_too_long | The source is over 60 seconds. | No |
422 | invalid_parameter | prompt is missing for retouch. | No |
422 | invalid_parameter | images is missing for swap, or has more photos than the kind accepts. | No |
422 | idempotency_key_mismatch | The same Idempotency-Key was already used with a different body. | No |
503 | temporarily_unavailable | The request could not be completed just now. | Yes |
500 | internal_error | Something failed on our side. The request_id identifies the request. | Yes |
503 | api_unavailable | The API is turned off. | No |
A second fix of a video that is still being fixed, for example, returns 409 and creates nothing:
{
"error": {
"type": "conflict",
"code": "fix_in_progress",
"message": "Another fix of this video is still queued or in progress.",
"fix": "Wait until it finishes (GET /api/v1/generations/{id}?wait_s=20), then send this request again.",
"charged": false,
"retryable": true
},
"request_id": "req_k38ss8hmb36g9308sy351ot3yi"
}