Seedance 2.5 — API reference

Seedance 2.5 uses the model ID bytedance/seedance-2.5/video-extend. Seedance 2.5 Video Extend generates extended video content from an input video URL and text prompt, supporting up to 30 seconds duration and optional audio or image inputs. It outputs videos in 480p, 720p or 1080p resolution with mp4 or mov format, allowing control over audio generation and multiple media inputs.

1. Calling the API

Send requests to https://api.higgsfield.ai/bytedance/seedance-2.5/video-extend with a JSON body matching the parameters below.

Install

Install an official server-side SDK. cURL needs no package.

npm install @higgsfield/client

Setup

Keep credentials in server-side environment variables. The SDKs accept the same KEY_ID:KEY_SECRET value under their documented variable names.

export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL

Request parameters

Parameter	Type	Required	Default	Description
`prompt`	`string`	Yes	`—`	Minimum length: 1.
`duration`	`integer`	No	`5`	Minimum: 4. Maximum: 30.
`video_url`	`string`	Yes	`—`
`audio_urls`	`array[string]`	No	`—`
`image_urls`	`array[string]`	No	`—`
`resolution`	`string`	No	`"720p"`	Options: 480p, 720p, 1080p.
`video_urls`	`array[string]`	No	`—`
`output_format`	`string`	No	`"mp4"`	Options: mp4, mov.
`generate_audio`	`boolean`	No	`true`

2. Authentication

The official SDKs read credentials from the server environment and send the required Authorization: Key KEY_ID:KEY_SECRET header.

API Key

Never expose the secret in browser-side code or commit it to source control. The TypeScript SDK is server-side only. For direct HTTP calls, use:

Authorization: Key $HF_KEY

3. Queue

subscribe submits the asynchronous request and waits for a terminal result. The TypeScript SDK polls automatically when withPolling: true; the Python SDK's synchronous subscribe call also waits. A completed request returns the generated file in the video field.

Submit and wait

import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "bytedance/seedance-2.5/video-extend",
  {
    input: {
      "prompt": "A cinematic scene at sunset",
      "duration": 5,
      "video_url": "https://example.com/input.mp4",
      "resolution": "720p",
      "output_format": "mp4",
      "generate_audio": true
    },
    withPolling: true,
  },
);

console.log(result);

Explicit lifecycle control

Use the Python SDK when a worker needs explicit status, result, or cancellation control for an existing request. The TypeScript v2 client currently exposes automatic polling through subscribe.

import higgsfield_client

request_id = "{request_id}"
status = higgsfield_client.status(request_id=request_id)
result = higgsfield_client.result(request_id=request_id)
higgsfield_client.cancel(request_id=request_id)