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

The submit request returns a task ID after acceptance. Your application then checks the task status rather than keeping a single request open for the entire generation. Completion time varies by model and queue conditions.

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.apimart.cc/v1/videos \
  -H "Authorization: Bearer $HIPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tk-wan3.0-video",
    "prompt": "A cinematic drone shot flying over misty mountains at sunrise",
    "seconds": 5,
    "metadata": {
      "resolution": "1080P",
      "ratio": "16:9"
    }
  }'

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.apimart.cc/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
unknownOutcome needs reconciliation; contact support before resubmitting

Completed response:

{
  "id": "vt-abc123def",
  "object": "video",
  "status": "completed",
   "model": "tk-wan3.0-video",
  "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
  • Deadline: Set a bounded application polling deadline; reaching it does not cancel the task
  • Backoff: If you’re making many concurrent requests, consider increasing the interval

Video Output

Section titled “Video Output”

For the video models described here, a completed response includes a url field pointing to the generated video file. If a completed task has no usable result URL, retain the task ID and contact support rather than resubmitting automatically.

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”