FicReel API

Overview

The FicReel backend = two domains: the content engine (/v1 — presets, worlds, generation, rendering, quality checks, cost) and the account domain (auth, quota, subscriptions, admin). Frontend, CLI and any agent share the same API. All public traffic goes through the API gateway (auth / quota / rate limiting / event tracking).

• Task model: submit → poll GET /v1/tasks/{id} → creations[].url. Outputs are mirrored to COS + EdgeOne CDN automatically (cdn.ficreel.com/ce/...); local /v1/files is the fallback path.
• Credit rates: image 3 credits, video 4 credits/second, music 7 credits, render 0 credits (server compute). Credits are the billing unit — /pricing shows what each plan costs. New devices get 150 trial credits, which cover one complete 30-second watermarked short (6 shots + a score) with a little left for a retry.
• Rate limits: reads 120/min/IP, writes 5/min/IP (in-memory token bucket, per node).

Projects (storyboard → per-shot generation → export)

A project is the server-side timeline for one reel: the storyboard skeleton plus the generated per-shot clips, the music bed and the final export. The wizard stops at the storyboard skeleton; per-shot generation, music and export all happen in the editor — there is no one-click full film.

• Live since 2026-09-14: these endpoints are served in production. Creating a project costs 0 credits — it only plans the shots.
• Workflow: the wizard only produces the skeleton (segments start in state "empty" and cost 0 credits). Generation is per shot, in the editor; music and export are separate calls. There is no single request that renders a whole film.
• Costing: image 3 credits, video 4 credits/second, music 7 credits, render 0 credits. A generation reserves credits up front and settles or refunds at terminal state. A 45-second film = 9 × 5s shots (180) + one score (7) = 187 credits.
• Export timing: call POST /v1/projects/:id/music first and poll GET /v1/tasks/{id} until the score is terminal (music.state === "done" or "failed") before exporting. Exporting while a submitted score is still rendering is rejected with 409 {error:"music_not_ready", music_state, detail} — no cut is produced, so you can never receive a silent cut without audio through this path. Only an export with no score at all comes back without audio; check export.note when present.

Presets (five-block assembly assets)

Four asset classes — worldview / style / character / shot. Registrable, referenceable, composable. Public presets are original (platform-neutral, D009).

• Shot payload fields: camera (camera-language block), motion (subject movement), avoid_list, duration, aspect_ratio, resolution?, movement_amplitude? — when gen video does not pass duration/aspect explicitly, the shot defaults are applied.

World Space

Shared worldview universes: World Card → World Page (modules JSON protocol) → Entity (characters / items / scenes / rules).

• Pages are data, not code: modules[] are rendered by the frontend renderer according to theme_tpl (classic template live: hero/characters/items/scenes/codex/gallery).

Generation (unified task model)

Image R2I / video R2V / music text2audio. Video requires reference2video: without reference images the server auto-generates the character baseline image first.

• Each references element = a public http(s) URL or a /v1/files/ relative path (converted to public automatically).
• prompt_override / prompt semantics = full replacement (not append); when omitted, the engine assembles the five blocks.
• off_peak = off-peak queue (upstream occasionally returns InternalServiceFailure — no credits charged, the engine retries once on the on-peak queue automatically).
• Failed generations roll quota back automatically; successes settle against the pre-reserve; the ledger is queryable via /v1/cost.

Tasks (polling / cancel)

Rendering (EDL edit + post)

Deterministic post chain: edit + color grade + music + watermark. light tier is synchronous only when the cut finishes inside the server window (~15s) — longer cuts come back as 202 and must be polled.

{
  "segments": [{ "src": "<local path or /v1/files/...>", "in": 0, "dur": 0, "speed": 1 }],
  "grade": { "saturation": 1.14, "contrast": 1.05, "bloom": 0.22, "vignette": "PI/5.5", "grain": 3 },
  "tier": "light | heavy-2k | heavy-interp",
  "output": { "w": 1080, "h": 1920, "fps": 25 },
  "title": "ASCII only (non-ASCII titles skip the title card)",
  "audio": { "src": "<bgm local path or /v1/files/...>", "volume": 0.35, "loop": true },
  "watermark": false
}

• dur: 0 = the whole segment (server probes the duration); speed ≠ 1 changes playback speed.
• Score ordering: a submitted score is still rendering while GET /v1/projects/:id reports music.state of queued/running/created. Exporting a project in that window is refused with 409 music_not_ready (body: {error, music_state, task_id, detail}) instead of producing a cut without audio — poll the score task until success/failed, then export again.
• tier: light (default, ≈7s per 10s of footage) / heavy-2k (2K upscale, async) / heavy-interp (60fps interpolation, ≈4.5 min, off by default). "light" is synchronous only up to the server window (~15s of wall-clock); anything longer returns 202 + task_id and must be polled.
• watermark = trial preview watermark (persistent bottom-right corner); paying plans omit it.

Quality checks (verify)

A 6-frame grid + metric checks + a human confirmation slot; the generate → verify → retry programmatic loop.

Prompt assembly (presets/build)

• Assembly order: worldview → character → motion → camera → style → anchor; character_id accepts preset characters or in-world entities.

Cost ledger

File serving

Accounts (auth / quota / subscription / admin)

• The legacy creator tools (/projects, /workbench node graph, /generations old pipeline) still work, based on the generation domain (that pipeline is temporarily disabled); all new features go through /v1.

Examples

# CLI (log in once, then everything goes through the gateway; admin JWT bypasses quota)
node apps/cli/src/index.mjs login --token <JWT> --base https://api.ficreel.com
node apps/cli/src/index.mjs preset build --world white-mist-station --style anime-90s --character saku --shot platform-walk
node apps/cli/src/index.mjs gen video --preset shio-morning --audio <bgm> --out out/
node apps/cli/src/index.mjs verify --jobs render --latest
node apps/cli/src/index.mjs cost --month 2026-09

# curl (generate a video: signed-in user, quota pre-reserved)
curl -X POST https://api.ficreel.com/v1/generations/video \
  -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" \
  -d '{"worldview_id":"white-mist-station","style_id":"anime-90s","character_id":"saku","shot_id":"platform-walk","duration":5}'
# → {"task_id":"...","prompt":"..."}
curl https://api.ficreel.com/v1/tasks/<task_id>   # poll until success → creations[].url

# curl (create a project — the storyboard skeleton; per-shot generation comes later)
curl -X POST https://api.ficreel.com/v1/projects \
  -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" \
  -d '{"worldview_id":"white-mist-station","character_id":"saku","style_id":"anime-90s","story":"A girl waits for a train that never comes.","shots":9,"shot_seconds":5}'
# → 201 {"project":{"model":"ficreel-1.0","segments":[{"state":"empty"}]}}