flux-3 Video Editing API: Continuation Guide

HiAPI

"Editing" here means something specific: flux-3 (FLUX.3 Video, from Black Forest Labs) extends an existing clip — continuing its motion, camera work, and sound into new footage — or builds a shot from an ordered sequence of keyframe images. It does not trim, cut, mask, color-grade, or otherwise touch footage in place. If you came here looking for a clip editor, the FAQ below is the fastest way to find out whether flux-3 is actually the right tool before you write any code.

What it's genuinely good at: taking a video you already have and generating a continuation that keeps the same subject, camera language, and audio — useful for extending a shot that cut off too early, or chaining several generated segments into one longer take. A separate mode takes a list of still images as ordered keyframes and generates the motion between them, which functions like a storyboard-driven edit even though no existing video is involved.

1. What you need

An hiapi API key (sk-...) from the dashboard. flux-3 is called through the same unified task API as every other hiapi model, so nothing here is model-specific setup — if you've called any other hiapi video model before, you already have what you need.

2. Minimal runnable example

Create a task, then poll it (or use a callback — see Production patterns) until it reaches a terminal state.

# 1. Create the task — continuation mode (start_video)
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3",
    "input": {
      "prompt": "continue the pan, camera keeps drifting right, same lighting",
      "start_video": "https://your-cdn.example.com/source-clip.mp4",
      "duration": 5,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": true
    }
  }'
# -> {"data": {"id": "task_...", "status": "pending"}}

# 2. Poll until terminal
curl -s https://api.hiapi.ai/v1/tasks/task_... \
  -H "Authorization: Bearer sk-<your-key>"
# -> {"data": {"id": "task_...", "status": "succeeded",
#              "output": [{"url": "https://...mp4", "expireAt": "..."}]}}

start_video is a single public HTTPS URL pointing at an MP4 (capped at 50MB and 15 seconds of source footage) — that's the clip flux-3 continues from. duration is an integer from 5 to 20 seconds and controls the length of the new generated segment, not the combined output. resolution is 720p or 1080p; aspect_ratio accepts auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, or 9:16. generate_audio is a boolean — when true, the model produces ambient sound baked directly into the output MP4 rather than as a separate audio file. Set draft: true while you're iterating on a prompt; draft jobs are cheaper but force resolution down to 720p only (a request with draft: true and resolution: "1080p" is rejected).

Keyframe storyboards (not editing existing footage)

The other input mode swaps start_video for image_urls — an ordered array of 1 to 10 image URLs that flux-3 treats as a storyboard, generating the motion that connects them in sequence:

{
  "model": "flux-3",
  "input": {
    "prompt": "smooth dolly move through each scene in order",
    "image_urls": [
      "https://your-cdn.example.com/keyframe-1.jpg",
      "https://your-cdn.example.com/keyframe-2.jpg",
      "https://your-cdn.example.com/keyframe-3.jpg"
    ],
    "duration": 8,
    "resolution": "720p"
  }
}

image_urls and start_video are two different task shapes on the same model — don't send both in one request. Use image_urls when you're building a shot from scratch out of stills; use start_video when you already have generated (or source) footage you want to carry forward.

3. Production patterns

Callbacks over polling for anything at scale. Pass a callback object in the same request body instead of polling in a loop:

{
  "model": "flux-3",
  "input": { "...": "..." },
  "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
}

when: "final" fires once, on whichever terminal state the task reaches — succeeded or failed are both terminal, so dedupe your webhook handler by taskId rather than assuming a callback only ever means success. Polling GET /v1/tasks/:id is the better fit for local debugging, low-volume one-offs, or as a reconciliation fallback if a callback never arrives.

Idempotency. Retries after a timeout or dropped connection can create duplicate (billable) tasks if you're not careful — track the task id you get back from the create call and make retries a GET on that id before you consider submitting a new one.

Output URLs expire. The expireAt field on each output entry is not decorative — download and persist the video to your own storage as soon as the task succeeds, whether you learn that from a callback or a poll.

Auth failures. A bad or missing key returns HTTP 401 with {"error": {"code": "permission_denied", ...}}. Check for that status/code explicitly rather than assuming any non-2xx means the generation itself failed — "my key is wrong" and "the model rejected my input" need different fixes.

Validate media URLs before you submit them. start_video and image_urls are checked for type and format, not for whether the file at that URL actually exists or decodes — a syntactically-valid-but-broken URL can still create a task that runs for a few seconds before failing, rather than getting rejected up front. Confirm your URLs actually resolve before wiring them into a batch job.

flux-3 model page — full parameter reference, playground, and current per-second, per-resolution pricing for all three modes (text-to-video, keyframe storyboards, and continuation).
Create Task docs — the full /v1/tasks request/response reference, including callback options.
Authentication docs — how the Authorization: Bearer sk-... header and key scoping work.
First and Last Frame Control in AI Video — a related recipe for models that interpolate between two still frames, if flux-3's multi-keyframe storyboard mode isn't granular enough for your shot.
hiapi pricing — current rates (continuation is priced higher than standard generation, and draft mode is cheaper than either — check the live page rather than a hardcoded number).

5. FAQ

Can flux-3 trim, cut, mask, or color-grade an existing video? No. flux-3's "video-to-video" mode is continuation — it generates new footage that carries forward the subject, camera motion, and sound of a source clip. It doesn't modify frames that already exist. There's no hiapi model today that does timeline-style trim/cut editing or masked region edits on video.

What's the difference between continuation and keyframe storyboards? Continuation (start_video) needs an existing video file and extends it. Keyframe storyboards (image_urls) need only still images and generate the motion between them — no source video required. They're mutually exclusive inputs on the same flux-3 model id.

Can I combine start_video and image_urls in one request? No — pick one mode per task. Sending both is not a supported input shape.

Does draft: true work with continuation mode? Yes, and it's the cheaper way to iterate on a continuation prompt before committing to a full-resolution run — but like standard mode, draft continuation is capped at 720p.

Why did my task fail almost instantly instead of taking the usual generation time? The most common cause is a start_video or image_urls entry that doesn't actually resolve to a valid file at request time — the API accepts syntactically well-formed URLs without fetching them synchronously, so a bad link surfaces as a fast failed status rather than an upfront validation error.

How long can my source clip be for continuation mode? Up to 15 seconds and 50MB, as an MP4. Longer or larger source files aren't accepted as start_video input.