Seedance 2.0 — Reference to video API

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

Usage notes

Use publicly accessible media URLs; asset:// references are rejected for these endpoints.
Provide a nonempty image_urls or video_urls array. Audio alone does not satisfy the reference requirement. Do not mix reference arrays with image_url, end_image_url or video_url.
Reference videos may be resized, transcoded and trimmed to 15 seconds each. Reference audio is normalized to 2–15 seconds per file and at most 15 seconds total.

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.0/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.0/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.0/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: 15.

array

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

array

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

string

default:"720p"

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

array

Ordered public video reference URLs. Minimum items: 1. Maximum items: 3. 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".

boolean

default:"true"

Generate audio with the video.

Complete JSON schema

{
  "if": {
    "required": [
      "image_urls"
    ]
  },
  "else": {
    "required": [
      "video_urls"
    ]
  },
  "type": "object",
  "required": [],
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "Write your prompt here"
    },
    "duration": {
      "type": "integer",
      "default": 5,
      "maximum": 15,
      "minimum": 4
    },
    "audio_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 3,
      "minItems": 1
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 9,
      "minItems": 1
    },
    "resolution": {
      "enum": [
        "480p",
        "720p",
        "1080p",
        "4k"
      ],
      "type": "string",
      "default": "720p"
    },
    "video_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "maxItems": 3,
      "minItems": 1
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16",
        "21:9"
      ],
      "type": "string",
      "default": "16:9"
    },
    "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.0 — 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