Wan 3.0 Prime — Reference to video API

← Wan 3.0 Prime Endpoint: POST https://api.higgsfield.ai/alibaba/wan-3.0-prime/reference-to-video Endpoint ID: alibaba/wan-3.0-prime/reference-to-video ▶Open API PlaygroundWan 3.0 Prime · Reference to video↗

Usage notes

Reference media are optional in the stored schema: only prompt is required. The example includes an image to demonstrate reference mode.
Send either file_url or link_url. A document or web-page reference automatically enables thinking; when both are sent, file_url takes precedence.
Reference video clips must be 1–30 seconds each and total at most 30 seconds. Reference audio must be WAV or MP3 and total at most 30 seconds, as specified in the production schema.
The schema accepts seed=0, but the current implementation only forwards a nonzero seed.

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/alibaba/wan-3.0-prime/reference-to-video \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --data '{
  "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
  "image_urls": [
    "https://example.com/input.jpg"
  ]
}'

import higgsfield_client

arguments = (
    {'prompt': 'A cinematic wide shot of ocean waves at sunset, with gentle camera '
               'movement.',
     'image_urls': ['https://example.com/input.jpg']}
)
result = higgsfield_client.subscribe(
    "alibaba/wan-3.0-prime/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("alibaba/wan-3.0-prime/reference-to-video", {
  input:
    {
      "prompt": "A cinematic wide shot of ocean waves at sunset, with gentle camera movement.",
      "image_urls": [
        "https://example.com/input.jpg"
      ]
    },
  withPolling: true,
});

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

Input schema

integer

Seed used to control generation randomness. Minimum: 0. Maximum: 2147483647.

string

required

Write your prompt here

integer

default:"5"

2-30 seconds. Minimum: 2. Maximum: 30.

string

One document (docx/xlsx/pptx/pdf/md). Forces deep thinking. Format: uri.

string

One public page. Forces deep thinking. Not combinable with file_url. Format: uri.

array

Up to 5 files, 30s total. WAV or MP3. Maximum items: 5. Each item: string. Format: uri.

array

Ordered public image reference URLs. Maximum items: 10. Each item: string. Format: uri.

string

default:"1080p"

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

array

Up to 5 clips, 30s total, each 1-30s. Maximum items: 5. Each item: string. Format: uri.

string

default:"adaptive"

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

boolean

default:"true"

Generate audio with the video.

boolean

default:"false"

Enable model reasoning.

Complete JSON schema

{
  "type": "object",
  "title": "Wan 3.0 Prime Reference to Video",
  "required": [
    "prompt"
  ],
  "properties": {
    "seed": {
      "type": "integer",
      "title": "Seed",
      "maximum": 2147483647,
      "minimum": 0
    },
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "description": "Write your prompt here"
    },
    "duration": {
      "type": "integer",
      "title": "Duration (sec)",
      "default": 5,
      "maximum": 30,
      "minimum": 2,
      "description": "2-30 seconds."
    },
    "file_url": {
      "type": "string",
      "title": "Reference Document",
      "format": "uri",
      "description": "One document (docx/xlsx/pptx/pdf/md). Forces deep thinking."
    },
    "link_url": {
      "type": "string",
      "title": "Reference Web Page",
      "format": "uri",
      "description": "One public page. Forces deep thinking. Not combinable with file_url."
    },
    "audio_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "title": "Reference Audio",
      "maxItems": 5,
      "description": "Up to 5 files, 30s total. WAV or MP3."
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "title": "Reference Images",
      "maxItems": 10
    },
    "resolution": {
      "enum": [
        "480p",
        "720p",
        "1080p"
      ],
      "type": "string",
      "title": "Resolution",
      "default": "1080p"
    },
    "video_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri"
      },
      "title": "Reference Videos",
      "maxItems": 5,
      "description": "Up to 5 clips, 30s total, each 1-30s."
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16",
        "adaptive"
      ],
      "type": "string",
      "title": "Aspect Ratio",
      "default": "adaptive"
    },
    "generate_audio": {
      "type": "boolean",
      "title": "Sound",
      "default": true
    },
    "enable_thinking": {
      "type": "boolean",
      "title": "Deep Thinking",
      "default": 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 polling, request errors and authentication for shared request handling.

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Wan 3.0 Prime — 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