Seedance 2.5 — Reference to video API

← Seedance 2.5 Endpoint: POST https://api.higgsfield.ai/bytedance/seedance-2.5/reference-to-video Endpoint ID: bytedance/seedance-2.5/reference-to-video ▶Open API PlaygroundSeedance 2.5 · Reference to video↗

Usage notes

Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
Provide at least one nonempty reference array: image_urls, video_urls or audio_urls. Audio-only references are supported by this schema and preprocessing path.
Reference media are limited to 30 images, 10 videos and 10 audio files, with at most 50 items total. Video duration and audio duration are normalized separately to at most 30 seconds total per media type.

Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

curl --request POST \
  --url https://api.higgsfield.ai/bytedance/seedance-2.5/reference-to-video \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
  "image_urls": [
    "https://example.com/input.jpg"
  ]
}'

import higgsfield_client

arguments = (
    {'image_urls': ['https://example.com/input.jpg']}
)
result = higgsfield_client.subscribe(
    "bytedance/seedance-2.5/reference-to-video",
    arguments=arguments,
)
print(result["video"]["url"])

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

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

const result = await higgsfield.subscribe("bytedance/seedance-2.5/reference-to-video", {
  input:
    {
      "image_urls": [
        "https://example.com/input.jpg"
      ]
    },
  withPolling: true,
});

if (result.status === "completed") {
  console.log(result.video?.url);
}

Input schema

string

Write your prompt here Minimum characters: 1.

integer

default:"5"

Requested output duration in seconds. Minimum: 4. Maximum: 30.

array

Ordered public audio reference URLs. Minimum items: 1. Maximum items: 10. Each item: string. Format: uri.

array

Ordered public image reference URLs. Minimum items: 1. Maximum items: 30. Each item: string. Format: uri.

string

default:"720p"

Output resolution tier. Allowed values: "480p", "720p", "1080p".

array

Ordered public video reference URLs. Minimum items: 1. Maximum items: 10. Each item: string. Format: uri.

string

default:"16:9"

Output width-to-height ratio. Allowed values: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9".

string

default:"high"

Allowed values: "standard", "high".

boolean

default:"true"

Generate audio with the video.

Complete JSON schema

{
  "if": {
    "required": [
      "image_urls"
    ]
  },
  "else": {
    "if": {
      "required": [
        "video_urls"
      ]
    },
    "else": {
      "required": [
        "audio_urls"
      ]
    }
  },
  "type": "object",
  "required": [],
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "Write your prompt here"
    },
    "duration": {
      "type": "integer",
      "default": 5,
      "maximum": 30,
      "minimum": 4
    },
    "audio_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 10,
      "minItems": 1
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 30,
      "minItems": 1
    },
    "resolution": {
      "enum": [
        "480p",
        "720p",
        "1080p"
      ],
      "type": "string",
      "default": "720p"
    },
    "video_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 10,
      "minItems": 1
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16",
        "21:9"
      ],
      "type": "string",
      "default": "16:9"
    },
    "bitrate_mode": {
      "enum": [
        "standard",
        "high"
      ],
      "type": "string",
      "default": "high"
    },
    "generate_audio": {
      "type": "boolean",
      "default": true
    }
  },
  "additionalProperties": false
}

Response

Submission returns a request handle. Poll status_url until status is completed, or use webhooks.

Accepted

{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}

A completed response includes the following output fields:

{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}

See idempotent requests, polling, request errors and authentication for shared request handling.

Requests

Models

Seedance 2.5 — Reference to video API

Usage notes

Quick start

Input schema

Response

​Usage notes

​Quick start

​Input schema

​Response

Usage notes

Quick start

Input schema

Response