Skip to content
HiPix Docs

Video Generation Overview

How It Works

Section titled “How It Works”

HiPix video generation uses a two-step asynchronous API:

Step 1: Submit Task     →  Returns task_id immediately
Step 2: Poll for Result  →  Returns video URL when ready

This design means your application never blocks waiting for a video to render (which takes 1-5 minutes). Instead, you submit a task and check back.

Step 1: Submit a Task

Section titled “Step 1: Submit a Task”

Send a POST request to /v1/videos:

Terminal window
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": "A cinematic drone shot flying over misty mountains at sunrise",
    "seconds": 5,
    "metadata": {
      "resolution": "1080P",
      "ratio": "16:9",
      "watermark": false
    }
  }'

Response:

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

Save the id — you’ll use it to poll for the result.

Step 2: Poll for the Result

Section titled “Step 2: Poll for the Result”

Send a GET request to /v1/videos/{task_id}:

Terminal window
curl https://api.hipix.app/v1/videos/vt-abc123def \
  -H "Authorization: Bearer $HIPIX_API_KEY"

Status progression:

StatusMeaning
queuedTask is waiting to be processed
in_progressModel is generating the video
completedVideo is ready, URL available
failedGeneration failed, see error details

Completed response:

{
  "id": "vt-abc123def",
  "object": "video",
  "status": "completed",
  "model": "aliyun/wan3-0/reference-to-video-global",
  "created_at": 1760000000,
  "completed_at": 1760000180,
  "url": "https://cdn.example.com/output/video.mp4"
}

Polling Recommendations

Section titled “Polling Recommendations”
  • Interval: Every 5 seconds is a good starting point
  • Timeout: Most videos complete within 1-5 minutes; set your client timeout to 10 minutes
  • Backoff: If you’re making many concurrent requests, consider increasing the interval

Video Output

Section titled “Video Output”

The completed response includes a url field pointing to the generated video file. This URL is served from our CDN.

Download your videos

The video URL may expire after a period of time. We recommend downloading and storing the video file yourself as soon as it’s completed. Don’t build your application assuming the URL will be permanently available.

Next Steps

Section titled “Next Steps”