Poll Video Results

Endpoint

GET https://api.hipix.app/v1/videos/{task_id}

Response Format

While Processing

{
  "id": "vt-abc123def",
  "object": "video",
  "model": "aliyun/wan3-0/reference-to-video-global",
  "status": "in_progress",
  "progress": 45,
  "created_at": 1760000000
}

When Completed

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

When Failed

{
  "id": "vt-abc123def",
  "object": "video",
  "model": "aliyun/wan3-0/reference-to-video-global",
  "status": "failed",
  "created_at": 1760000000,
  "error": {
    "code": "generation_failed",
    "message": "Content policy violation detected in prompt"
  }
}

Status Values

Status	Description	Action
queued	Task waiting in queue	Continue polling
in_progress	Model generating video	Continue polling
completed	Video ready	Download from url
failed	Generation failed	Check error field

Polling Strategy

import time
import requests

def wait_for_video(task_id, api_key, max_wait=600, interval=5):
    """Poll until the video task reaches a terminal state."""
    start = time.time()
    while time.time() - start < max_wait:
        resp = requests.get(
            f"https://api.hipix.app/v1/videos/{task_id}",
            headers={"Authorization": f"Bearer {api_key}"},
        ).json()

        if resp["status"] == "completed":
            return resp
        if resp["status"] == "failed":
            raise RuntimeError(f"Video failed: {resp.get('error', 'unknown')}")

        time.sleep(interval)

    raise TimeoutError(f"Video did not complete within {max_wait}s")

Handling Timeouts

If your polling loop times out:

1. The task may still be running — check again later with the same task ID
2. Don’t resubmit immediately — you’d be charged for a duplicate
3. Task IDs are valid for 24 hours — you can check the result at any time within that window

Video URL

The url field in a completed response points to the generated video file.

URLs may expire

We recommend downloading the video file to your own storage as soon as it’s completed. Don’t rely on the URL being permanently available.

# Download the video
video_data = requests.get(resp["url"]).content
with open("output.mp4", "wb") as f:
    f.write(video_data)

Billing

You are billed when the task is submitted, not when it completes. If a task fails:

• The charge is automatically refunded to your balance
• The refund may take a few minutes to appear
• You can verify by checking your Wallet transaction history