The Hubfluencer API.

Overview & authentication

Send every protected request with an Authorization header. The token is opaque (a session token or a Personal Access Token) — it is not a JWT, so don't decode it.

authorization: Bearer <token>
content-type: application/json

Scopes gate what a token can do: video:read for reads, video:generate for anything that spends credits, account:admin for account/token management. Agent tokens get video:generate + video:read only.

Prefer docs your agent can read directly? Download the Markdown mirror of this page: API.md . A machine-readable OpenAPI spec also lives at /api/openapi (Bearer-gated in production).

Response envelope

// Success — usually wrapped in `data` (a few endpoints return the object at top level)
{ "data": { "...": "..." }, "error": null, "meta": { "timestamp": "2026-06-03T10:00:00Z" } }

// Error — shapes vary; parse defensively
{ "error": "credits_insufficient", "message": "Not enough credits.", "required_credits": 15, "available_credits": 3 }
{ "errors": { "product_prompt": ["should be at least 10 character(s)"] } }

Access tokens

Personal Access Tokens are the recommended credential for agents. The token string is returned only once on creation. Managing tokens needs account:admin — so an agent token can't mint or revoke tokens; create one while signed in to the app (Settings → Access tokens), or run npx -y @hubfluencer/mcp@0.20.0 login.

curl -X POST https://hubfluencer.com/api/tokens \
  -H "authorization: Bearer $SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"Claude Code","scopes":["video:generate","video:read"]}'

201 Created
{
  "data": {
    "id": 42,
    "name": "Claude Code",
    "scopes": ["video:generate", "video:read"],
    "token": "hf_pat_9f3c…ONCE_ONLY",
    "inserted_at": "2026-06-03T10:00:00Z"
  }
}

200 OK
{
  "data": [
    { "id": 42, "name": "Claude Code",
      "scopes": ["video:generate","video:read"],
      "last_used_at": "2026-06-03T10:05:00Z",
      "inserted_at": "2026-06-03T10:00:00Z" }
  ]
}

Credits & voices

200 OK
{ "data": { "credits": 120 } }

POST /api/studio/agent/turns
Idempotency-Key: studio-turn:<stable-turn-id>
{"messages":[{"role":"user","content":"Tighten the intro"}],"tools":[...],"context":{"digest":{...}},"quality":"standard","max_tokens":4096}

event: tool_use
data: {"type":"tool_use","name":"ripple_delete_range","input":{"start":0,"end":1.8}}

200 OK
{
  "data": {
    "voices": [
      { "voice_id": "rachel", "name": "Rachel",
        "verified_languages": [
          { "language": "en", "accent": "american", "locale": "en-US",
            "preview_url": "https://…/rachel-en.mp3" }
        ] }
    ],
    "has_more": false,
    "total_count": 1,
    "next_page_token": null
  }
}

Generation runs & recovery

Editor and Short product responses are the normal read surface. These endpoints inspect one authorized run or execute an exact needs-input action already advertised by generation_summary.available_actions. Never invent a recovery action from product projection fields. Re-read the product immediately before a command and echo its run_id, revision, and action step_key; a stale fence fails without touching newer work.

All four recovery commands require video:generate and an Idempotency-Key. Reuse one key only for transport retries of the same fenced body; a deliberate new approval/input command gets a fresh key. The input object must be non-empty. A spend-cap approval is append-only and does not rewrite the frozen run policy. Success returns {data:{generation_summary}}; re-read it before the next action. A missing key returns 422 idempotency_key_required.

POST /api/editor/:slug/generation/input
Idempotency-Key: recovery:<stable-command-id>
{"generation_run_id":"<uuid>","generation_revision":7,"step_key":"brief","input":{"product_name":"Acme"}}

Shorts

A short is a single-prompt vertical ad composed from two connected clips. Three requests: create a draft (free), start generation (15 credits), then follow the required generation_summary until it stops advertising a polling cadence. A generation may pause at a visual-review gate between clips; invoke only the advertised recovery action to continue. Send an Idempotency-Key on generate so a retry doesn't double-charge.

Every Editor and Short product read includes a non-null generation_summary. Treat it as the sole lifecycle authority even when stage, autopilot_status, batch_generation_status, child statuses, or latest_render disagree. Poll only while generation_summary.timing.poll_after_ms is a positive integer, exactly at that server cadence; null means stop polling. Read terminality from generation_summary.status, invoke only generation_summary.available_actions, and download only when download_result is advertised for a verified delivery artifact. Product projection fields are display metadata or explicit route fences only; never derive polling, retry, cancel, or download availability from them.

curl -X POST https://hubfluencer.com/api/shorts \
  -H "authorization: Bearer $HF" -H "content-type: application/json" \
  -d '{"product_prompt":"a 15s ad for my soy candle brand","language":"en","creative_format":"proof_demo","visual_language":"kinetic_creator"}'

201 Created
{
  "data": {
    "slug": "amber-candle-9x2",
    "stage": "draft",
    "generation_summary": {
      "run_id": null, "workflow": null, "workflow_version": null, "revision": null,
      "status": "idle", "settling": false, "phase": "idle", "label": "Ready to generate",
      "progress": {"completed": 0, "total": 0, "percent": 0}, "current_step": null,
      "blockers": [],
      "available_actions": [{"type":"start_generation","label":"Start generation","destructive":false,"step_key":null}],
      "failure": null,
      "cost": {"quoted_credits":0,"charged_credits":0,"refunded_credits":0,"net_credits":0,"max_credits":0},
      "timing": {"started_at":null,"updated_at":null,"deadline_at":null,"poll_after_ms":null}
    },
    "language": "en",
    "latest_render": null,
    "inserted_at": "2026-06-03T10:00:00Z"
  }
}

curl -X POST https://hubfluencer.com/api/shorts/amber-candle-9x2/text/generate \
  -H "authorization: Bearer $HF"

curl -X POST https://hubfluencer.com/api/shorts/amber-candle-9x2/generate \
  -H "authorization: Bearer $HF" \
  -H "idempotency-key: gen-short:amber-candle-9x2"

# edit any free field first (0 credits), then re-render — free, no body
curl -X PATCH https://hubfluencer.com/api/shorts/amber-candle-9x2 \
  -H "authorization: Bearer $HF" -H "content-type: application/json" \
  -d '{"cta_text": "Order today"}'
curl -X POST https://hubfluencer.com/api/shorts/amber-candle-9x2/rerender \
  -H "authorization: Bearer $HF" \
  -H "idempotency-key: rerender-short:amber-candle-9x2:v2"

200 OK  — poll only while generation_summary.timing.poll_after_ms is positive
{
  "data": {
    "slug": "amber-candle-9x2",
    "generation_summary": {
      "run_id": "5d379ddd-6687-41cb-a1be-d2684875335f",
      "workflow": "short.generation", "workflow_version": 1, "revision": 14,
      "status": "completed", "settling": false, "phase": "completed", "label": "Video ready",
      "progress": {"completed": 4, "total": 4, "percent": 100}, "current_step": null,
      "blockers": [],
      "available_actions": [{"type":"download_result","label":"Download video","destructive":false,"step_key":null}],
      "failure": null,
      "cost": {"quoted_credits":15,"charged_credits":15,"refunded_credits":0,"net_credits":15,"max_credits":15},
      "timing": {"started_at":"2026-06-03T10:00:00Z","updated_at":"2026-06-03T10:03:00Z","deadline_at":null,"poll_after_ms":null}
    },
    "stage": "video_ready",
    "failed_stage": null,
    "failure_code": null,
    "failure_details": null,
    "failure_source": null,
    "failure_attempt": null,
    "segments_completed": 2,
    "segments_total": 2,
    "active_segment_positions": [],
    "error_message": null,
    "latest_render": {
      "status": "completed",
      "video_url": "https://…/amber-candle-9x2.mp4?X-Amz-Expires=86400"
    }
  }
}

Branding images — product, logo & end-card poster

All are 0 credits and use a presign → PUT raw bytes → confirm flow. On the single PUT, send Content-Type matching the presigned mime. Product images accept jpeg/png up to 20 MB and are woven into generated footage. Logos accept jpeg/png up to 5 MiB and are composited deterministically by Forge, never sent to the video model. End-card posters additionally accept webp and are limited to 20 MB. A never-uploaded, oversized, or corrupt image is rejected at confirm (422).

Tracking overlay

Upload your own video and get it back with a computer-vision tracking overlay burned on top (convex-hull polygons hugging each moving subject, HUD brackets, a crosshair, and per-subject telemetry). Source clip must be 60s or shorter and 1080p or lower. Create a draft (free), set the source clip — either upload it via the editor upload routes with the tracking slug, or reuse a library video via /source/from-asset — then render (1 credit). The source clip is deleted once the render completes.

Sliders (image carousels)

A slider is a social-media carousel: one prompt produces N still slides (an AI background + a composited headline/body + optional logo) plus a ready-to-post caption and hashtags. No video — save the images and copy the text. Create a draft (free), then generate (1 credit per slide ⇒ 3–10 credits; default 5 slides = 5 credits). Generation is async: poll GET /api/sliders/:slug until status is completed or failed. Editing slide text, or the template/accent/logo, re-renders for free.

Editor ads — autopilot

An editor ad is a multi-scene, story-driven video. Autopilot runs the whole pipeline server-side (scenario → scenes → narration → voice → music → render). Create the project with an exact 3–10 scene target, start autopilot, then follow generation_summary; download only when its available_actions advertises download_result. A 3-scene run is ~20 credits and a 5-scene run is ~28 (batch scene rate + voice + music); preflight the exact figure with GET /api/editor/:slug/autopilot/cost.

POST /api/editor/:slug/autopilot transparently selects the inverted topology editor.autopilot.voicefirst@1 when the project is in voice_first pacing (see Voice spine — pacing modes). Its order is scenario.compile → scenario.review → scenario.apply → narration → voice → pacing.derive → previews → scenes (generated at the derived durations) → scene reviews → music → render → delivery. The request and response contract is unchanged: the caller never picks a workflow, it only sets the pacing mode.

Every Editor and Short product read includes a non-null generation_summary. Treat it as the sole lifecycle authority even when stage, autopilot_status, batch_generation_status, child statuses, or latest_render disagree. Poll only while generation_summary.timing.poll_after_ms is a positive integer, exactly at that server cadence; null means stop polling. Read terminality from generation_summary.status, invoke only generation_summary.available_actions, and download only when download_result is advertised for a verified delivery artifact. Product projection fields are display metadata or explicit route fences only; never derive polling, retry, cancel, or download availability from them.

curl -X POST https://hubfluencer.com/api/editor \
  -H "authorization: Bearer $HF" -H "content-type: application/json" \
  -d '{"language":"en","product_prompt":"a cinematic ad for my candle brand","segments_count":3,"export_aspect_ratio":"9:16"}'
# then start autopilot:
ATTEMPT_ID="$(uuidgen)"
curl -X POST https://hubfluencer.com/api/editor/$SLUG/autopilot \
  -H "authorization: Bearer $HF" -H "idempotency-key: autopilot:$SLUG:$ATTEMPT_ID"

ATTEMPT_ID="$(uuidgen)"
curl -X POST https://hubfluencer.com/api/editor/$SLUG/autopilot \
  -H "authorization: Bearer $HF" -H "content-type: application/json" \
  -H "idempotency-key: autopilot:$SLUG:$ATTEMPT_ID" \
  -d '{"language":"fr","product_subject":"Bordeaux red wine, dark green bottle with a gold label","product_prompt":"a concise cinematic social ad for my wine","segments_count":3,"max_credits":20}'

200 OK  — generation_summary owns lifecycle, cadence, and action availability
{
  "data": {
    "slug": "candle-story-7k1",
    "generation_summary": {
      "run_id": "60d15a8b-b987-4412-838e-3441b89eeb6d",
      "workflow": "editor.autopilot", "workflow_version": 1, "revision": 42,
      "status": "completed", "settling": false, "phase": "completed", "label": "Video ready",
      "progress": {"completed": 8, "total": 8, "percent": 100}, "current_step": null,
      "blockers": [],
      "available_actions": [{"type":"download_result","label":"Download video","destructive":false,"step_key":null}],
      "failure": null,
      "cost": {"quoted_credits":20,"charged_credits":20,"refunded_credits":0,"net_credits":20,"max_credits":20},
      "timing": {"started_at":"2026-06-03T10:00:00Z","updated_at":"2026-06-03T10:08:00Z","deadline_at":null,"poll_after_ms":null}
    },
    "autopilot_status": "completed",
    "autopilot_contract_satisfied": true,
    "autopilot_error_message": null,
    "scenario_prompt": "Warm, handcrafted… ",
    "segments_count": 5,
    "segments": [
      { "id": 81, "position": 1, "prompt": "Macro of wax pouring…", "status": "completed" },
      { "id": 82, "position": 2, "prompt": "Hands trimming the wick…", "status": "completed" }
    ],
    "narration_script": "Made by hand, poured in small batches…",
    "narration_script_source": "manual",
    "narration_status": "ready",
    "current_audio": { "status": "completed" },
    "current_music": { "status": "completed" },
    "latest_render": {
      "status": "completed",
      "video_url": "https://…/candle-story-7k1.mp4?X-Amz-Expires=86400",
      "is_stale": false
    }
  }
}

Granular editor pipeline

Same editor project, driven step by step instead of autopilot — write the scenario, set the scene count, hand-write each scene prompt, then generate. Reads need video:read; anything that generates needs video:generate. Each row is free (no credit, no assist), assist (1 AI assist), or credits.

* render auto-charges every still-missing scene at its selected model's generation price for 1–2 missing scenes, or batch_discounted price for 3+ — including previously FAILED AI scenes, which are revived and charged as missing work (failed uploads still block the render) — so a fully-generated project renders for 0. Historical seedance-2.0 scenes are selectable again and are quoted and auto-charged at the model's current catalog price; they used to hard-fail as an unavailable model. Before spending, read the live Editor video_models and current scenes, quote the exact ordered segment/model/pricing-version cohort, obtain approval, and send max_generation_credits plus generation_quote_fingerprint; a stale quote returns 409 generation_credit_quote_changed without starting. voice_id matches ^[A-Za-z0-9_-]+$ (≤64). Render waits for active narration/voice/music generation (409 narration_generation_in_progress / voice_generation_busy / music_generation_busy). A timeline longer than the 600s ceiling returns 422 editor_total_duration_exceeded; when a just-failed scene's refund is still settling, render returns a retryable 409 editor_render_settlement_pending (try again shortly). Editing the scenario or narration after generating voice/music marks them stale — render returns 422 editor_voice_stale / editor_music_stale / editor_narration_stale until you regenerate.

apply-scenario materializes the saved scenario into the timeline: existing AI scenes are replaced with scene prompts generated from the scenario, uploads are preserved, and segments_count 0 removes the AI scenes. It is free — no credits and no AI assist (generate-scenario already spent the assist) — and runs async: poll GET /api/editor/:slug until scenario_apply_status leaves "applying". When segments_count is omitted, apply uses the saved scenario brief's scene count, then defaults to 5. Read video_models from the Editor response before spending: it is the whole selectable fleet, each entry carrying tier, lifecycle, capabilities (including durations_seconds and native_audio), continuity implications, notices, and the pricing basis. generate/regenerate accept an optional model id and an optional generation_options object carrying duration_seconds (one of that model's capabilities.durations_seconds; omit it for the 8s model default) and native_audio. credits.generation/regeneration/batch_discounted are the price at that default; any other duration costs ceil(pricing.basis_micros_per_second * duration_seconds / 400000) + 1, with regeneration priced like generation and the 3+-scene batch rate one credit lower (minimum 1). An unsupported length returns 422 unsupported_generation_duration and any other option name returns 422 invalid_generation_options — neither creates a run or charges. DIALOGUE SCENES: native_audio true keeps the model's own sound for that scene and persists use_original_audio on the segment (PATCH /api/editor/:slug/segments/:id accepts the same flag directly). It is gated on the model's capabilities.native_audio.mode: optional takes both values (default false), always takes only true (422 native_audio_required otherwise — wan-2.7, happy-horse-1.1 and minimax-h3 return sound whatever you ask and are priced for it), and unavailable takes only false (422 native_audio_not_available). A dialogue scene is priced from the model's with-audio basis (pricing.audio_micros_per_second), which on Veo 3.1 Standard is double the silent rate: an 8s veo3 scene is 5 credits silent and 9 credits with audio. When native audio resolves TRUE the quote fingerprint gains a literal audio marker before the pricing version — six parts, segment_id:model:<operation>:duration_seconds:audio:pricing_version, for example 7:veo3:generation:8:audio:2026-08-09-unified-v1 at 9 credits. The marker follows the RESOLVED value, not whether your request carried the option, so an always-mode model and a scene already patched to use_original_audio: true both require the marked form even with no generation_options in the body; the silent five-part form and both duration-free forms are then refused with 409 generation_credit_quote_changed because they encode a price you were never shown. Variants fence the same way (segment_id:model:variants:count:duration_seconds:audio:pricing_version); the batch cohort fingerprint is unchanged and audio-blind, though a batch still prices each scene from its own persisted flag. A dialogue scene never speaks: it is excluded from narration, the voice run lays digital silence under it, the render hard-mutes narration across its window, and in voice_first pacing it is a fixed narration gap whose length the spine never resizes (toggling the flag sets pacing_stale). Every segment also carries a derived audio_role, computed and never sent: dialogue whenever the scene plays its OWN audio (use_original_audio true — the same answer for an AI take keeping model sound and an upload keeping its recorded sound; tell them apart with source_type), narrated when a voice-over line lands over it (its own narration_text under narration_script_source "segments", and every non-dialogue scene under "manual", where the one project script is split across the speaking set at voice time), and ambient otherwise. Fence an approved single-scene quote with max_generation_credits and generation_quote_fingerprint in the form segment_id:model:<operation>:duration_seconds:pricing_version, where operation is generation or regeneration; the duration-free segment_id:model:<operation>:pricing_version form is also accepted at the model default duration, for exactly two pricing_version values: the current pricing_version on the entry you just read, and the historical 2026-07-31 — the latter only for veo3, veo3-fast, and kling-o3-pro, and only while their prices are still the ones that version set (5/4/4, 3/3/3, 4/3/3). A stale model, duration, or pricing version returns 409 generation_credit_quote_changed before launch. batch-generate generates every scene at the SAME duration it would be generated at individually: the model default in scene_first, and the scene's authored_duration_seconds in voice_first — and it is now priced there too, so a batch and the equivalent one-by-one generations quote the same per-scene duration (the 3+ batch rate still applies on top). An explicit generation_options.duration_seconds is still accepted on single-scene generate/regenerate only. Voice-first Autopilot freezes the selectable-duration ceiling as the maximum approved spend, then resolves each exact scene charge from its immutable duration-price table after pacing.derive; scene-first Autopilot remains model-default priced. regenerate creates a NEW version of one scene; pass prompt and model to author the new version, or omit either to reuse the current selection. A completed scene cannot be re-run through generate (422 editor_segment_completed) — regenerate is the path to a fresh take. In voice_first pacing this all still holds, with one addition: when a scene has an authored_duration_seconds, THAT authored duration is the priced duration. It is what the credit formula, the generation_quote_fingerprint, and max_generation_credits all resolve to when the request carries no generation_options, so build the five-part v2 fingerprint segment_id:model:<operation>:duration_seconds:pricing_version from the served authored_duration_seconds (a 6s-paced scene fingerprints at 6, not at the 8s model default). The duration-free four-part segment_id:model:<operation>:pricing_version form is rejected for a scene paced away from the model default — it would understate the price — and stays accepted only at the model default duration. An explicit generation_options.duration_seconds still wins, but it must EQUAL the authored duration or the call is refused 422 editor_pacing_duration_mismatch (with the authored and requested values in details), so what the spine authored and what actually gets generated can never silently diverge. A project in which EVERY scene keeps its own audio has nothing left to speak: narration, generate-voice, voice-plan and autopilot all refuse it up front with 422 editor_no_speaking_segments, before any scene is charged. And because a take's audio is fixed when it is generated, PATCHing use_original_audio on an AI scene that already has a take returns 409 editor_segment_audio_locked — regenerate with generation_options.native_audio to change it. REFERENCE SLOTS (identity): references pin identity, last-frame chaining pins continuity, and a reference generation sends both — the scene's identity images first, the previous scene's visible boundary frame appended last — within the model's slot budget; filling every slot drops the continuity frame and sets continuity_limited: true. Every segment carries reference_s3_keys (ordered storage keys) and reference_urls (the same slots presigned for display, POSITIONALLY ALIGNED: reference_urls[i] shows reference_s3_keys[i], and an unsignable slot holds null rather than collapsing — send keys back, never URLs). A non-empty set REPLACES the project product photo for that scene rather than stacking on it, because slots are scarce and stacking would push the continuity frame out of the request. How many a model takes is capabilities.reference_images_max on its video_models entry — an integer alongside the existing boolean capabilities.reference_images, which is exactly reference_images_max > 0: veo3 and veo3-fast take 3, seedance-2.0 and seedance-2.0-fast take 9, and every other model takes 0. Exceeding it is 422 editor_reference_images_exceed_model_max, whose details name the model and its exact max_images, and it is refused at generation admission as well as at attach time. References never change the price and never enter the quote fingerprint: the reference route is the same fal endpoint family as the model's other routes and bills at the same per-second basis (the reference_route_same_price notice says so on the models where it is newly wired). Attach on a scene with no take yet through references/presign then references/confirm (image/jpeg, image/png or image/webp, at most 8MB), or references/from-asset for a catalog image (subscription-gated); remove with DELETE .../references/:index. All four are AI-scene-only: an uploaded clip's pixels already exist, so it answers 422 editor_segment_references_unsupported. Once the scene HAS a take those two writes return 409 editor_segment_references_locked — the images are the input that produced its pixels, so rewriting the column would make the row claim an identity the media never had. Stage the change instead: references/presign is always allowed (it writes nothing), PUT the image, then send generation_options.reference_s3_keys on regenerate and the new set lands on the new version row. references/from-asset degrades to stage-only there, returning staged: true with the asset's s3_key and the unchanged segment, leaving the column untouched — and it still refuses a staged set that would not fit the model, with the same 422 editor_reference_images_exceed_model_max. In generation_options the key is absent-means-inherit: omitting it keeps the scene's persisted references, an explicit [] clears them, every entry must be a key minted by this project's references/presign or the s3_key of a ready catalog image you own (anything else is 422 editor_reference_image_not_owned, because every staged key gets presigned), and the same per-model ceiling applies. A saved reference whose object has since disappeared fails the generation closed with 422 segment_reference_required rather than quietly producing a lookalike. PATCHing a scene's model is held to the same ceiling: a switch that would strand more references than the new model's reference_images_max is refused 422 editor_reference_images_exceed_model_max and writes nothing. And apply-scenario RE-AUTHORS the timeline, so its fresh scenes carry no reference_s3_keys — re-attach identity images after applying a scenario.

variants explores the SAME scene N ways at once instead of one at a time. Send count (2–4), the model, and both fences: max_credits must equal count × the per-take price exactly, and generation_quote_fingerprint takes the six-part form segment_id:model:variants:count:duration_seconds:pricing_version. Per-take price is the generation price while the scene has no completed take and the regeneration price once it does. Only the frontier scene can be explored (409 scene_not_frontier / scene_locked). Each take is staged as a candidate version of the same scene — the timeline is untouched — and the run then parks needs_input with available_actions advertising variant_select and blockers[].details.candidate_segment_ids listing the takes that finished. Answer it at POST /api/editor/:slug/generation/input with the ordinary fenced body and input {"segment_id": <chosen take id>}; the body never names the action. The chosen take becomes the scene, the rest stay in its take history with media and prompts intact (reachable through the versions/select route). A take that fails is refunded on its own and simply does not appear among the choices; if every take fails the run fails and nothing on the timeline changed. Cancel a live batch with POST /api/editor/:slug/generation/variants/cancel {generation_run_id, variant_batch_id} — the batch id fences out a successor fan-out on the same scene. Cancellation refunds only the takes that were not yet handed to the provider: a take already generating has been billed per attempt, so it runs to completion and is kept as an ordinary superseded take in the scene's history, media and prompt intact.

Finalize — draft → final

A model whose video_models entry carries tier "draft" (veo3-lite, seedance-2.0-fast) is the cheapest exploration tier: shoot the scene there, look at it, and commit the take you kept ONCE onto a standard or premium model with POST /api/editor/:slug/segments/:id/finalize. The draft take's prompt, identity reference_s3_keys, authored duration, and dialogue (native_audio) setting are copied verbatim — the model is the ONLY variable — and anything you pass in generation_options overrides the copied value for that one field. Mechanically it is a regeneration: a forward-only candidate take, previewed and reviewed, with the existing take staying selected until the new one passes, and the response is regenerate's exactly (a bare EditorSegment under data, carrying generation_summary). The workflow is editor.scene.finalize@1, and cancel and retry work exactly as for a scene regeneration — generation_summary.available_actions advertises cancel_generation (POST .../segments/:id/cancel) and, on failure, retry_generation (POST .../segments/:id/retry).

It is priced as a GENERATION on the TARGET model, not as a regeneration: a draft take is not a failed attempt at the target model, it is the first shot the scene has ever taken there. So the fingerprint's operation word is generation and the credits are the target model's credits.generation. The form is segment_id:model:generation:duration_seconds:pricing_version, where segment_id is the DRAFT take's id, model is the TARGET model, and duration_seconds is the resolved duration — the scene's authored/voice-first duration when it has one and the target model supports it, else the model default 8; a dialogue scene takes the six-part …:duration_seconds:audio:pricing_version form, exactly as on generate/regenerate. Both fences are mandatory here, unlike single generate/regenerate where they are optional, because a finalize always changes the model — you can never be of no opinion about the price. The promoted take reports draft_of_segment_id (integer, nullable) on the segment wire, naming the draft take it came from; to decide whether a take IS a draft (and should offer Finalize), read tier on its model's video_models entry — draft_of_segment_id is the result of a promotion, not the marker of a draft.

Two refusals are specific to this route, both 422: editor_finalize_requires_draft_take when the current take's model is not draft-tier (an unknown or retired model key counts), details naming model and tier; and editor_finalize_target_tier_invalid when the requested target model is itself draft-tier, details naming model and tier. Everything else it can return is the set regenerate returns: 402 credits_insufficient quoting the GENERATION price, 409 generation_credit_quote_changed, 422 invalid_max_generation_credits / invalid_generation_quote_fingerprint / editor_reference_images_exceed_model_max (checked against the TARGET model's capabilities.reference_images_max — it refuses, it never silently drops references) / editor_pacing_duration_mismatch / native_audio_*, 422 editor_segment_not_completed, 409 editor_segment_busy, and the 503 admission refusal. The admission gate for editor.scene.finalize@1 is closed by default in production until it is opened, so a fresh deploy answers 503 generation_admission_closed.

# The scene's current take was shot on a draft-tier model — its video_models entry says tier "draft"
# (veo3-lite, seedance-2.0-fast). Explore there, then commit the take you kept ONCE onto a
# quality model. Priced as a GENERATION on the TARGET model: veo3 is 5 credits at the 8s default.
curl -X POST https://hubfluencer.com/api/editor/$SLUG/segments/81/finalize \
  -H "authorization: Bearer $HF" -H "idempotency-key: finalize-seg:$SLUG:81" \
  -H "content-type: application/json" \
  -d '{"model":"veo3","max_credits":5,"generation_quote_fingerprint":"81:veo3:generation:8:2026-08-09-unified-v1"}'

# The response is regenerate's exactly: the EditorSegment under data — a candidate take carrying
#   "draft_of_segment_id": 81
# plus a generation_summary for editor.scene.finalize@1. The draft take stays selected until the
# new one passes. Prompt, reference_s3_keys, authored duration and native_audio were copied verbatim.

# generation_options overrides ONE copied field — here, keep the model's own sound (9 credits):
#   {"model":"veo3","max_credits":9,
#    "generation_quote_fingerprint":"81:veo3:generation:8:audio:2026-08-09-unified-v1",
#    "generation_options":{"native_audio":true}}

Scene prompts are screened for content-policy compliance at every paid generation entry (generate, regenerate, variants, batch-generate, and render's auto-charge): a violating prompt returns 422 prompt_rejected (code CONTENT_COMPLIANCE) with nothing charged; if screening is temporarily unavailable the call returns 503 compliance_unavailable (fail-closed, nothing charged — retry shortly).

Retry a failed Kernel-owned scene only when generation_summary.available_actions advertises retry_generation for editor.scene.generate or editor.scene.regenerate: quote that action's exact credits, obtain approval, then POST /api/editor/:slug/segments/:id/retry with generation_run_id, generation_revision, and step_key from the same action. Idempotency-Key is required. The failed provider attempt was refunded; the retried provider step is a new balance-gated charge at the immutable price frozen into the run. The route retries the exact failed run in place and rejects stale run/revision/step/materialization fences.

Cancel one in-flight scene with POST /api/editor/:slug/segments/:id/cancel (video:generate). Idempotency-Key is required; reuse it only for transport retries of this exact token-fenced command. Send {"expected_generation_claim_token": "<generation_claim_token from the processing scene>"} so a delayed command cannot cancel a successor attempt. The token is required and must be a non-empty string. It stops that individual generation, fences a racing provider completion (first writer wins), refunds the paid attempt idempotently, and returns the scene as failed with error_code user_cancelled — repeating the cancel with the same token and key returns that scene. A refunded cancel does not prepay the next attempt; the next generation or advertised frozen-price retry is separately paid. Batch or autopilot scenes are not individually cancellable (409 batch_generation_active / autopilot_active — use the batch or autopilot cancel commands); 409 editor_segment_not_processing when the scene has no active individual generation; 409 editor_segment_cancel_stale when the token targets an older attempt; 422 invalid_generation_claim_token when the required field is omitted or invalid; 404 for an unknown factory/segment; 503 editor_segment_cancel_failed if cancellation could not be settled — retry with the same key.

Voice spine — pacing modes

Every editor project has one authoritative pacing mode, served as pacing_mode on the editor payload. "scene_first" is the default and what every existing project uses: scene durations are authoritative and the voice-over is fitted to them with Forge's 0.80–1.25x playback-rate clamp — unchanged behavior. "voice_first" inverts the contract: the narration script is the project's spine. The voice is generated FIRST, before any scene is generated, each line is measured, and every scene's duration is derived from its line. A narration line can therefore never overrun its scene or collide with the next line, because the scene was sized from the line.

Switch with POST /api/editor/:slug/pacing, body mode: "scene_first" or "voice_first". It is free (0 credits), needs video:generate, and takes NO Idempotency-Key. It is refused 409 while any generation owns the project — a run planned under one contract must never have the other applied to it halfway through. Switching TO voice_first flags every scene that has no authored_duration_seconds yet as pacing_stale: true; switching TO scene_first clears every pacing_stale flag and KEEPS any authored durations (they stay an honest record of what was requested). The response is the ordinary editor factory payload plus a pacing_impact object carrying marked_stale, cleared_stale, and scenes_without_authored_duration. An unknown mode returns 422 editor_pacing_mode_invalid.

POST /api/editor/:slug/voice-plan plans the spine — body voice_id (required), style?, tone?; Idempotency-Key is REQUIRED; video:generate. It starts the workflow editor.voice.plan@1: narration.generate (free of credits, spending the AI-assist quota exactly like the ordinary narration endpoint), then voice.generate (3 credits, ElevenLabs with-timestamps), then pacing.derive (free, 0 credits) — 3 credits total. It requires the project to be in voice_first pacing (422 editor_pacing_mode_required otherwise) and at least one scene that does not keep its original audio. The scenes do NOT need to be generated yet; that is the whole point of the mode. A 201 returns the editor factory payload, and the generation_summary key is OMITTED entirely when there is nothing to report — never present-but-null.

The derivation is authored_duration_seconds = snap_up_to_model_grid(line_duration + 0.4s lead + 0.5s tail + continuity_head_trim). line_duration is the MEASURED spoken length taken from the ElevenLabs character timestamps. The lead and tail default to 0.4s and 0.5s and are server-tunable per deployment. continuity_head_trim is 0.2s (6 frames at 30fps) for every scene after the first whose use_previous_frame is true — the render trims those conditioning frames off the scene's head, so the spine budgets them up front. Snapping up to the model grid uses the scene model's capabilities.durations_seconds: Veo accepts 4/6/8, so a 5.1s requirement becomes a 6s scene and the surplus is planned tail air, never a clipped word. The authored duration is CAPPED at the catalog's default duration (8s) — for EVERY scene, including a model with no published duration grid — so a derived spine can never cost more than the price the user approved. A line that does NOT FIT that cap is refused before any credit moves: voice-plan (and the voice step of a voice-first Autopilot) returns 422 editor_narration_line_too_long with details.scenes naming each offending scene (segment_id, position, estimated_line_seconds, max_authored_seconds). It is neither clipped nor silently over-bought — a scene generated at the cap while the voice run is laid at its full measured length produces a canvas the picture cannot cover. Shorten the line, or split it across more scenes, and plan again. Uploads are never resized by the spine: an uploaded scene is a fixed gap at its measured length (a 30s upload stays 30s whether or not narration is spoken over it), and a line too long to fit inside one is refused by the same 422. Every authored duration is snapped onto the render's 1/30s frame grid — up for a derived scene, down for a fixed upload — so the render's seconds-to-frames conversion is exact.

Two fields carry the spine on every read. The editor factory payload gains pacing_mode ("scene_first" or "voice_first"). Each segment gains authored_duration_seconds (float or null) — what the scene was ASKED for, the spine's derivation — where duration_seconds remains what the generated media MEASURES, and null means "model default"; and pacing_stale (boolean), true when this scene's narration line changed after its authored duration was derived. A pacing_stale scene is still renderable; it is simply no longer proven to fit its line.

# 1. Make the narration script this project's spine (free, 0 credits, no Idempotency-Key)
curl -X POST https://hubfluencer.com/api/editor/$SLUG/pacing \
  -H "authorization: Bearer $HF" -H "content-type: application/json" \
  -d '{"mode":"voice_first"}'

# 200 OK — the ordinary editor payload plus what the switch did to the timeline:
#   "pacing_mode": "voice_first",
#   "pacing_impact": {"marked_stale": 5, "cleared_stale": 0, "scenes_without_authored_duration": 5}

# 2. Plan the spine — 3 credits total, Idempotency-Key REQUIRED.
# The scenes do NOT have to be generated yet: the voice is what sizes them.
curl -X POST https://hubfluencer.com/api/editor/$SLUG/voice-plan \
  -H "authorization: Bearer $HF" -H "idempotency-key: voice-plan:$SLUG" \
  -H "content-type: application/json" \
  -d '{"voice_id":"rachel","tone":"warm"}'

# 3. Poll GET /api/editor/$SLUG. Every scene now carries what it was ASKED for:
#   { "id": 81, "duration_seconds": null, "authored_duration_seconds": 6.0, "pacing_stale": false }

# 4. Generate at the derived duration. Omit generation_options and the AUTHORED
# duration is the priced duration — the fingerprint must carry it (6, not 8).
curl -X POST https://hubfluencer.com/api/editor/$SLUG/segments/81/generate \
  -H "authorization: Bearer $HF" -H "idempotency-key: gen-seg:$SLUG:81" \
  -H "content-type: application/json" \
  -d '{"model":"veo3-fast","max_generation_credits":3,"generation_quote_fingerprint":"81:veo3-fast:generation:6:2026-08-09-unified-v1"}'

Batch recovery

The retry body is {generation_run_id, generation_revision}; the cancel body is {generation_run_id}. Copy these fields from the generation_summary that advertises the action. Missing or malformed fences return 422 batch_command_required, while fences that were valid but moved on return 409 generation_authority_changed. Re-poll and issue a new command with a new Idempotency-Key only when the current summary still advertises the action.

generation_summary.available_actions is the only source of retry/cancel availability. batch_generation_status, batch_generation_run_id, and batch_generation_failed_position are product display projections; they do not authorize commands, select polling cadence, or determine terminality. While a retry action is advertised, the rest of the timeline stays mutation-locked except the failed scene identified by current_step. An insufficient-credit blocker is resolved only through the action advertised by generation_summary after a top-up or scope reduction.

# Write your own scenario instead of generating it (free, no assist)
curl -X PATCH https://hubfluencer.com/api/editor/$SLUG/scenario \
  -H "authorization: Bearer $HF" -H "content-type: application/json" \
  -d '{"scenario_prompt":"Scene 1 … Scene 2 … Scene 3 …"}'

# Read GET /api/editor/$SLUG first, choose from data.video_models, and obtain approval for its exact credits/notices
# Generate one scene with Veo 3.1 Fast (3 credits at the 8s default in the 2026-08-09-unified-v1 catalog); poll until completed
curl -X POST https://hubfluencer.com/api/editor/$SLUG/segments/81/generate \
  -H "authorization: Bearer $HF" -H "idempotency-key: gen-seg:$SLUG:81" \
  -H "content-type: application/json"   -d '{"model":"veo3-fast","max_generation_credits":3,"generation_quote_fingerprint":"81:veo3-fast:generation:8:2026-08-09-unified-v1"}'

# Author a non-default scene length: pick a value from the model's capabilities.durations_seconds
# and price it as ceil(pricing.basis_micros_per_second * duration_seconds / 400000) + 1
curl -X POST https://hubfluencer.com/api/editor/$SLUG/segments/81/generate \
  -H "authorization: Bearer $HF" -H "idempotency-key: gen-seg-12s:$SLUG:81" \
  -H "content-type: application/json"   -d '{"model":"kling-o3-pro","generation_options":{"duration_seconds":12},"max_generation_credits":5,"generation_quote_fingerprint":"81:kling-o3-pro:generation:12:2026-08-09-unified-v1"}'

# Voice-over (3 credits), then render. This 0-credit fence succeeds only after every scene is generated.
# If scenes are missing, GET the Editor again, quote the exact ordered cohort, obtain approval, and send that cap/fingerprint.
curl -X POST https://hubfluencer.com/api/editor/$SLUG/generate-voice \
  -H "authorization: Bearer $HF" -H "content-type: application/json" -d '{"voice_id":"rachel"}'
curl -X POST https://hubfluencer.com/api/editor/$SLUG/render   -H "authorization: Bearer $HF" -H "idempotency-key: render:$SLUG"   -H "content-type: application/json"   -d '{"max_generation_credits":0,"generation_quote_fingerprint":""}'

Uploads & local assets

Bring your own media into an editor project — your own footage as scenes, plus a product image, closing card, and brand logo. All of this is free (0 credits). Uploads use a presign → PUT-to-storage → confirm flow; the file then processes asynchronously before it can go on the timeline.

200 OK
{
  "data": {
    "upload_id": 510,
    "presigned_url": "https://r2…/editor/$SLUG/uploads/uuid.mp4?X-Amz-Signature=…",
    "s3_key": "editor/$SLUG/uploads/uuid.mp4",
    "expires_in_seconds": 3600
  }
}

200 OK  — status flows pending → processing → ready | failed
{
  "data": [
    { "id": 510, "filename": "clip.mp4", "mime_type": "video/mp4",
      "status": "ready", "duration_seconds": 6.2, "width": 1080, "height": 1920,
      "error_message": null, "attached_segment_ids": [83] }
  ]
}

Large files use a resumable multipart flow (use it at ≥ 50 MiB / 52,428,800 bytes, 8 MiB parts): POST …/uploads/multipart/init, …/sign-part, …/complete, …/abort. init returns part_size + parts_count; sign each part, PUT its bytes, keep the ETag, then send the ordered parts list to complete (abort on failure).

Image assets — product, closing card, logo

Same presign → PUT → confirm shape (image/jpeg or image/png). Product images are capped at 8 MiB, closing cards at 20 MiB, and logos at 5 MiB. Thread the s3_key from presign into confirm verbatim.

The old compatibility routes have been removed entirely — POST product/apply-default-placement, scene-asset presign/confirm/impact, and reference-images/impact no longer exist in the router and now return a plain 404. Only the body-level fences on segment add/update survive: product_placement or product_excluded returns 410 product_placement_removed, scene_asset_role / scene_asset_prompt_adaptation_enabled / scene_asset_s3_key returns 410 scene_assets_disabled, and any other unknown field returns 422 unsupported_field. Author scene content through prompt and use_previous_frame.

Full flow

# 1. Presign (Content-Type MUST equal the mime_type you send here)
curl -X POST https://hubfluencer.com/api/editor/$SLUG/uploads/presign \
  -H "authorization: Bearer $HF" -H "content-type: application/json" \
  -d '{"filename":"clip.mp4","mime_type":"video/mp4","size_bytes":4821004}'

# 2. PUT the bytes to presigned_url with the SAME Content-Type
curl -X PUT "$PRESIGNED_URL" -H "content-type: video/mp4" --data-binary @clip.mp4

# 3. Confirm — queues processing (metadata + frame extraction)
curl -X POST https://hubfluencer.com/api/editor/$SLUG/uploads/510/confirm -H "authorization: Bearer $HF"

# 4. Poll GET /api/editor/$SLUG/uploads until the row's status is "ready"
# 5. Drop it on the timeline as a finished scene
curl -X POST https://hubfluencer.com/api/editor/$SLUG/segments/from-upload \
  -H "authorization: Bearer $HF" -H "content-type: application/json" -d '{"upload_id":510}'

Renders

200 OK
{
  "data": [
    { "id": 9, "version": 2, "status": "completed",
      "video_url": "https://…/render.mp4?X-Amz-Expires=86400",
      "thumbnail_url": "https://…/render.jpg?X-Amz-Expires=86400",
      "duration_seconds": 18.0, "error_message": null, "retryable": false,
      "combination_hash": "v2:…", "is_stale": false,
      "inserted_at": "2026-06-03T10:20:00Z" },
    { "id": 8, "version": 1, "status": "failed",
      "video_url": null, "error_message": "forge_timeout", "retryable": true }
  ]
}

AI disclosure & compliance (EU AI Act Art. 50)

Every render — editor ad, short, and carousel slide — carries C2PA Content Credentials (a signed, machine-readable "this is AI-generated" marking with the generator model list) AND a visible AI-disclosure badge that is ON by default. Distribution platforms (TikTok, Meta, YouTube) read the C2PA manifest at upload and may auto-apply their own AI label from it — so turning the badge off does NOT prevent platform labels. Publishing the video makes YOU the deployer under Art. 50(4): the disclosure assessment is your decision, which is why disabling the badge requires an explicit acknowledgement that is stamped and logged.

Badge controls live on the project and are set via the normal update endpoints (PATCH /api/editor/:slug and PATCH /api/shorts/:slug): ai_disclosure_mode ("generated" default | "modified" | "none") and ai_disclosure_position ("auto" default — the corner opposite your logo, inside the platform-safe area — or an explicit corner). Setting mode "none" without ai_disclosure_ack: true in the same request returns 422 ai_disclosure_ack_required. A successful disable stamps ai_disclosure_ack_at / ai_disclosure_ack_by_user_id (returned on the project and in the compliance record) and writes an audit log entry; switching back on never clears the historical stamp. Carousels are always fully AI-generated and are always marked + labelled (no per-slider toggle).

// Turning the label off is an explicit, acknowledged decision:
PATCH /api/editor/:slug   (or /api/shorts/:slug)
{ "ai_disclosure_mode": "none", "ai_disclosure_ack": true }

// Without the ack in the SAME request:
422 { "error": "ai_disclosure_ack_required", "message": "…" }

200 OK
{
  "data": {
    "kind": "editor",
    "ai_disclosure": {
      "mode": "generated", "position": "auto",
      "ack_at": null, "ack_by_user_id": null
    },
    "provenance": {
      "contains_user_footage": false,
      "models": ["veo3", "elevenlabs-tts", "elevenlabs-music"],
      "machine_readable_marking": "c2pa"
    },
    "renders": [
      { "video_result_id": 42, "status": "completed",
        "generated_at": "2026-08-01T12:00:00Z" }
    ]
  }
}

Product sources

The start of the "delegate my content" loop: turn a product page into facts and imagery. Every fetch is SERVER-SIDE and SSRF-guarded (https only, no redirects to internal ranges). Extraction is stateless; import stores a catalog asset. All three spend 0 credits, need video:generate, and are rate-limited to 30/min.

Product & brand profiles

Reusable, user-owned identity so every campaign draft inherits it instead of re-describing the brand. A product profile grounds the AI (benefits, offer, proof points, audience, CTA, compliance); a brand profile steers tone/format and carries the logo. Plain CRUD; reads need video:read, writes need video:generate; all 0 credits. Only name is required on each.

Campaign packs

The planning container: plan a campaign, persist it as a pack, and materialize each item into an editable DRAFT (an editor/short video project or an image slider). Planning (plan + hook-variations) generates no media and consumes the FREE AI-assist quota — NOT credits. Persisting a pack and materializing items are 0 credits. Generating/rendering each draft is a SEPARATE, explicit, PAID step (autopilot / generate). Reads need video:read, writes need video:generate.

Series & episodes

A series is a reusable recurring-content show template ("Myth vs Fact", "Founder Tip") bound to an optional brand + product profile. The planner drafts upcoming episode IDEAS (free AI-assist quota); materialize turns an idea into a 0-credit draft grouped under the series' rolling campaign pack. Reads need video:read, writes need video:generate; all 0 credits.

Performance

Attach lightweight performance snapshots + creative-attribute tags to a campaign-pack ITEM (item_id from GET /api/campaign-packs/:id), then read a CAUTIOUS aggregate over your own items. Reads need video:read, writes need video:generate; all 0 credits (only make-more consumes the free AI-assist quota).

Review links

Mint an expiring, hashed-token review link for ONE completed output so a reviewer opens /review/:token with no account. The plaintext token + URL are returned ONCE (only the hash is stored) — surface them immediately. Reads need video:read, writes need video:generate; all 0 credits.

Asset catalog

Your reusable asset library (images + videos). Uploading here lets an asset be reused across projects via the from-asset routes on shorts / sliders / editor / tracking. Reads need video:read, writes need video:generate; all 0 credits. Subscription-gated: these routes return 402 subscription_required without an active subscription.

Scheduled posts (content calendar)

Schedule a COMPLETED render for a future posting time. A reminder-only schedule (no social account attached) fires a push notification at the scheduled time — you post manually, then close the loop with mark-posted. An agent token (video:generate) can create, reschedule, cancel, and mark these reminder-only schedules, so it can run the whole content calendar. Attaching a social account turns a schedule into an AUTO-PUBLISH: that additionally requires account:admin and is app-only (do it signed in to the app), and auto-posting to TikTok/Instagram is gated on posting access besides. Reads need video:read.

AI assists

AI helper calls draw from a free daily quota of 20, account-wide — separate from credits. This covers every content-drafting endpoint: the editor's generate-scenario, generate-narration, enhance-prompt, and suggest-* (music-prompt / next-scene); shorts text/generate; campaign-packs plan and hook-variations; series episodes/plan; and make-more. When it runs out you either unlock more (1 credit → +10) or write the content yourself with the free PATCH endpoints.

200 OK
{
  "data": {
    "used": 4, "limit": 20, "bonus": 0, "remaining": 16,
    "resets_at": "2026-06-04T00:00:00Z",
    "unlock_cost": 1, "unlock_batch_size": 10
  }
}

Errors, rate limits & polling

402 Payment Required
{ "error": "credits_insufficient", "required_credits": 15, "available_credits": 3 }

429 Too Many Requests
{ "error": "ai_assist_quota_exceeded", "remaining": 0,
  "can_unlock": true, "unlock_cost": 1, "unlock_batch_size": 10 }

Rate limits

Where a route is rate-limited, the per-user cap is listed below; requests over it are rejected — back off for a minute and retry. Everything else is governed only by credits and the AI-assist quota.