SeraStudio FixCreate fix

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.

SeraStudio Fix
POSThttps://serastudio.app/api/v1/fix/generations

Usage 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 202 the fix is queued and billing.held_usd is 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_version to 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-Key header (1 to 255 ASCII characters). A retry with the same key and body returns the existing generation with 200; a different body returns 422 idempotency_key_mismatch.
  • Follow progress with Get generation and wait_s, or send webhook_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."}'

Input schema

sourceobjectrequired

The 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_snumberrequired

Start of the range in seconds from the beginning of the video.

end_snumberrequired

End of the range in seconds. Must be greater than start_s and not past the end of the video.

source_duration_snumber

Measured length of the video in seconds, up to 60. Required when the source is an upload. A finished generation uses its stored length.

promptstring

What to fix inside the range, in English. Required for retouch, optional for swap and fill.

imagesarray

Reference 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_versionstring

Id of a finished fix of this video to build on. Leave it out to build on the newest one.

webhook_urlstring

Public https URL that receives the generation when it finishes. Optional. See Webhooks.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <api-key>
Idempotency-KeyNo1 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.kindstring

The kind that was requested.

fix.start_s, fix.end_snumber

The range that is replaced. fill rounds its length to whole seconds.

fix.window_secondsnumber

Whole seconds sent to the model and billed.

fix.video_idstring

The video this fix belongs to: the same value for every fix of one video.

fix.on_versionstring

The fix this one was built on, or null when it was built on the untouched source.

fix.retry_discount_pctnumber

50 when this request repeated a finished fix of the same range, otherwise 0.

See Get generation for the other fields.

Errors

StatusCodeWhen it happensRetry
400invalid_jsonThe body is not a JSON object.No
400invalid_idempotency_keyThe Idempotency-Key header is empty, longer than 255 characters or not printable ASCII.No
401api_key_missingNo Bearer key was sent in the Authorization header.No
401api_key_invalidThe key is malformed or unknown.No
401api_key_revokedThe key was deleted in the console.No
401api_key_disabledThe key is disabled in the console.No
401api_key_expiredThe key is past its expiration date.No
403insufficient_scopeThe key lacks the create permission. Keys created in the console have it.No
403workspace_forbiddenThe account that owns the workspace is suspended or scheduled for deletion.No
402insufficient_balanceThe price of this fix is larger than the workspace balance. Nothing was created.No
404not_foundAn upload id or the source generation does not exist in this workspace, or no file was put to the upload address.No
409source_not_readyThe source generation has not finished, failed, or its output was deleted.No
409version_unavailableon_version is not a finished fix of this video, or its output is no longer stored.No
409fix_in_progressAnother fix of the same video is queued or in progress.Yes
422invalid_parameterA field is missing or has the wrong type or value. error.param names the field.No
422invalid_parameterend_s is past the end of the source, the range is empty, or it is longer than the kind remakes at a time.No
422source_too_shortThe whole source is shorter than the seconds this kind sends to the model.No
422source_too_longThe source is over 60 seconds.No
422invalid_parameterprompt is missing for retouch.No
422invalid_parameterimages is missing for swap, or has more photos than the kind accepts.No
422idempotency_key_mismatchThe same Idempotency-Key was already used with a different body.No
503temporarily_unavailableThe request could not be completed just now.Yes
500internal_errorSomething failed on our side. The request_id identifies the request.Yes
503api_unavailableThe 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"
}