Submit a Video Task

Endpoint

POST https://api.hipix.app/v1/videos

Request Headers

Header	Required	Description
Authorization	Yes	Bearer sk-your-api-key
Content-Type	Yes	application/json

Request Body

Top-Level Fields

Field	Type	Required	Description
model	string	Yes	Model ID (see Available Models)
prompt	string	Yes	Text description of the video to generate
seconds	integer	No	Duration in seconds (default: 5)
metadata	object	No	Additional generation parameters

Metadata Fields

Field	Type	Values	Default	Description
resolution	string	480P, 720P, 1080P	720P	Output resolution
ratio	string	1:1, 16:9, 9:16, 4:3, 3:4, adaptive	1:1	Aspect ratio
watermark	boolean	—	false	Whether to add a watermark
media	array	—	—	Reference media (see below)
negative_prompt	string	—	—	What to avoid in the generation

Reference Media

For reference-to-video models, provide reference images or videos:

{
  "model": "aliyun/wan3-0/reference-to-video-global",
  "prompt": "The person in image 1 is walking through the scene in video 1",
  "seconds": 5,
  "metadata": {
    "resolution": "720P",
    "ratio": "16:9",
    "media": [
      { "type": "reference_image", "url": "https://example.com/person.jpg" },
      { "type": "reference_video", "url": "https://example.com/scene.mp4" }
    ]
  }
}

Media types:

Type	Description	Limits
reference_image	Reference image	Up to 10 per request
reference_video	Reference video (also billed)	Up to 5, total ≤15 seconds
reference_audio	Reference audio	Up to 5, total ≤15 seconds
first_frame	First frame image	1 only

Reference videos are billed

The total billed duration = output video seconds + reference video seconds. See Pricing for details.

Duration Limits

Duration ranges vary by model:

Model	Range	Notes
Wan 3.0 series	4–30 seconds	Use -1 for auto-duration
Wan 2.7 series	4–150 seconds	Text-to-video supports longer
HappyHorse	4–15 seconds

Response

{
  "id": "vt-abc123def",
  "object": "video",
  "status": "queued",
  "created_at": 1760000000
}

Field	Type	Description
id	string	Task ID — use this to poll for results
status	string	Initial status (always queued)
created_at	integer	Unix timestamp

Examples

Text-to-Video

curl -X POST https://api.hipix.app/v1/videos \
  -H "Authorization: Bearer $HIPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aliyun/wan3-0/text-to-video",
    "prompt": "A slow pan across a cyberpunk city at night, neon signs reflecting in puddles",
    "seconds": 5,
    "metadata": { "resolution": "720P", "ratio": "16:9" }
  }'

Image-to-Video (Single Reference)

curl -X POST https://api.hipix.app/v1/videos \
  -H "Authorization: Bearer $HIPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aliyun/wan3-0/image-to-video",
    "prompt": "The character starts walking forward, camera follows",
    "seconds": 5,
    "metadata": {
      "resolution": "720P",
      "media": [{ "type": "first_frame", "url": "https://example.com/frame.jpg" }]
    }
  }'

Reference-to-Video (Multiple Inputs)

curl -X POST https://api.hipix.app/v1/videos \
  -H "Authorization: Bearer $HIPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aliyun/wan3-0/reference-to-video-global",
    "prompt": "Person from image 1 walks through the garden in image 2, speaking the words in audio 1",
    "seconds": 10,
    "metadata": {
      "resolution": "1080P",
      "ratio": "16:9",
      "media": [
        { "type": "reference_image", "url": "https://example.com/person.jpg" },
        { "type": "reference_image", "url": "https://example.com/garden.jpg" },
        { "type": "reference_audio", "url": "https://example.com/speech.mp3" }
      ]
    }
  }'