Pixazo API→Models→Hunyuan Video
Pixazo API→Models→Hunyuan Video

Hunyuan Video API

by Tencent

View as Markdown

Tencent's Hunyuan Video — high-quality text-to-video, image-to-video, and video-to-video generation.

Get API Key
Hunyuan Video API

Models Version

LIMITED TIME OFFER

Get $5 Free Credit on First Payment

No strings attached — add funds and get $5 bonus instantly

Claim Your $5 →

Hunyuan Video v1 Text to Video API Documentation

https://gateway.pixazo.ai/hunyuan-video/v1

Authentication

All requests require an API key passed via header.

Header Type Required Description
Ocp-Apim-Subscription-Key string Yes Your API subscription key

Hunyuan Video v1 Text to Video API Pricing

No data available

Could not load current pricing

Hunyuan Video v1 Image to Video API Documentation

https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1

Authentication

All requests require an API key passed via header.

Header Type Required Description
Ocp-Apim-Subscription-Key string Yes Your API subscription key

Hunyuan Video (Image to Video) generate request - Hunyuan Video (Image to Video)

Request Code

POST https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "prompt": "Two muscular cats boxing in a boxing ring.",
  "image_url": "https://example.com/example_inputs/hunyuan_i2v.jpg"
}
import requests

url = "https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "Two muscular cats boxing in a boxing ring.",
    "image_url": "https://example.com/example_inputs/hunyuan_i2v.jpg"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
const url = "https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
};
const data = {
  "prompt": "Two muscular cats boxing in a boxing ring.",
  "image_url": "https://example.com/example_inputs/hunyuan_i2v.jpg"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));
curl -X POST "https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "Two muscular cats boxing in a boxing ring.",
    "image_url": "https://example.com/example_inputs/hunyuan_i2v.jpg"
  }'

Output

{
  "video": {
    "file_size": 14530500,
    "file_name": "output.mp4",
    "content_type": "application/octet-stream",
    "url": "[RESPONSE_URL]"
  }
}
Try Now

Request Parameters - Hunyuan Video (Image to Video) generate request

Field Type Required Default Description
prompt string Yes — Text description guiding the video generation. Must be detailed for best results.
image_url string Yes — Publicly accessible URL of the input image to convert into video. Must be reachable by the service.
seed integer No — Optional random seed for reproducible results. If omitted, a random seed is used.
aspect_ratio enum No 16:9 Aspect ratio of the output video. Allowed values: 16:9, 9:16.
resolution string No 720p Resolution of the generated video. Supported values: 720p, 1080p, 480p.
num_frames string No 129 Number of frames to generate. Supported values: 129, 65, 33.
i2v_stability boolean No false Enables I2V Stability mode, which reduces visual hallucinations at the cost of reduced motion dynamics.

Minimum Request

{
  "prompt": "Two muscular cats boxing in a boxing ring.",
  "image_url": "https://example.com/example_inputs/hunyuan_i2v.jpg"
}

Full Request (all options)

{
  "prompt": "Two muscular cats boxing in a boxing ring.",
  "image_url": "https://example.com/example_inputs/hunyuan_i2v.jpg",
  "seed": 42,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "num_frames": "129",
  "i2v_stability": false
}

Response

{
  "video": {
    "file_size": 14530500,
    "file_name": "output.mp4",
    "content_type": "application/octet-stream",
    "url": "[RESPONSE_URL]"
  }
}

Response Fields - Hunyuan Video (Image to Video) generate request

Field Type Description
video object Object containing video output details
video.file_size integer Size of the video file in bytes
video.file_name string Filename of the output video
video.content_type string MIME type of the video file
video.url string URL to download the generated video

Request Headers

Header Value
Content-Type application/json
Cache-Control no-cache
Ocp-Apim-Subscription-Key Your API subscription key

Response Handling

Common status codes for Hunyuan Video (Image to Video) generate request.

Code Meaning
200 Success
Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Too Many Requests
500 Internal Server Error

Error Responses

400 Validation Error

{
  "error": "Missing required parameter: prompt"
}

404 Not Found

{
  "error": "Resource not found"
}

Job Status Workflow

Poll the status endpoint to track progress after submitting a request.

Status Description
QUEUED Request accepted, waiting to be processed
PROCESSING Being processed by the model
COMPLETED Done — output contains the result
FAILED Failed — check error field for details
ERROR System error occurred — request was not processed and not charged

Status Flow

Submitted → QUEUED → PROCESSING → COMPLETED
                               ↘ FAILED
                               ↘ ERROR

Typical Workflow

  1. Submit request using POST /hunyuan-video-image-to-video-request
  2. Receive response with request_id
  3. Poll the status endpoint every 2–5 seconds with the request_id
  4. When status is COMPLETED, extract the video URL from output
  5. Download the video using the provided URL

Hunyuan Video (Image to Video) check status - Hunyuan Video (Image to Video)

Request Code

POST https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request-result
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "request_id": "hunyuan-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
import requests

url = "https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request-result"
headers = {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "request_id": "hunyuan-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
const url = "https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request-result";
const headers = {
  "Content-Type": "application/json",
  "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
};
const data = {
  "request_id": "hunyuan-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));
curl -X POST "https://gateway.pixazo.ai/hunyuan-video-image-to-video/v1/hunyuan-video-image-to-video-request-result" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "request_id": "hunyuan-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }'

Output

{
  "video": {
    "file_size": 14530500,
    "file_name": "output.mp4",
    "content_type": "application/octet-stream",
    "url": "[RESPONSE_URL]"
  }
}
Try Now

Request Parameters - Hunyuan Video (Image to Video) check status

Field Type Required Default Description
request_id string Yes — The unique identifier returned from the initial request to check status.

Minimum Request

{
  "request_id": "hunyuan-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Full Request (all options)

{
  "request_id": "hunyuan-video-image-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Response

{
  "video": {
    "file_size": 14530500,
    "file_name": "output.mp4",
    "content_type": "application/octet-stream",
    "url": "[RESPONSE_URL]"
  }
}

Response Fields - Hunyuan Video (Image to Video) check status

Field Type Description
video object Object containing video output details
video.file_size integer Size of the video file in bytes
video.file_name string Filename of the output video
video.content_type string MIME type of the video file
video.url string URL to download the generated video

Request Headers

Header Value
Content-Type application/json
Ocp-Apim-Subscription-Key Your API subscription key

Response Handling

Common status codes for Hunyuan Video (Image to Video) check status.

Code Meaning
200 Success
Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Too Many Requests
500 Internal Server Error

Usage Notes

  1. Poll the status endpoint every 2–5 seconds until COMPLETED, FAILED, or ERROR is returned.
  2. Implement exponential backoff for retry logic on ERROR or 500 responses.
  3. Use detailed, action-oriented prompts (e.g., “a cat jumps over a fence with motion blur”) for more dynamic results.
  4. For consistent outputs across runs, explicitly set the seed parameter.
  5. Ensure image_url points to a publicly accessible, static image with reasonable size (under 10MB recommended).
  6. Use i2v_stability: true for scenes requiring high visual fidelity over motion intensity.

Hunyuan Video v1 Image to Video API Pricing

No data available

Could not load current pricing

Hunyuan Video v1 Video to Video (Video Editing) API Documentation

https://gateway.pixazo.ai/hunyuan-video-video-to-video/v1

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour API subscription key

Hunyuan Video (Video to Video) generate request

Request Code

POST https://gateway.pixazo.ai/hunyuan-video-video-to-video/v1/hunyuan-video-video-to-video-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a dark blue leather jacket, a long pink dress, and bright yellow boots, and carries a black purse.",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "num_frames": 129,
  "enable_safety_checker": true,
  "video_url": "https://example.com/hunyuan_video/hunyuan_v2v_input.mp4",
  "strength": 0.85
}
import requests

url = "https://gateway.pixazo.ai/hunyuan-video-video-to-video/v1/hunyuan-video-video-to-video-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a dark blue leather jacket, a long pink dress, and bright yellow boots, and carries a black purse.",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "num_frames": 129,
    "enable_safety_checker": true,
    "video_url": "https://example.com/hunyuan_video/hunyuan_v2v_input.mp4",
    "strength": 0.85
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
const url = "https://gateway.pixazo.ai/hunyuan-video-video-to-video/v1/hunyuan-video-video-to-video-request";

const data = {
  prompt: "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a dark blue leather jacket, a long pink dress, and bright yellow boots, and carries a black purse.",
  aspect_ratio: "16:9",
  resolution: "720p",
  num_frames: 129,
  enable_safety_checker: true,
  video_url: "https://example.com/hunyuan_video/hunyuan_v2v_input.mp4",
  strength: 0.85
};

fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
curl -X POST "https://gateway.pixazo.ai/hunyuan-video-video-to-video/v1/hunyuan-video-video-to-video-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a dark blue leather jacket, a long pink dress, and bright yellow boots, and carries a black purse.",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "num_frames": 129,
    "enable_safety_checker": true,
    "video_url": "https://example.com/hunyuan_video/hunyuan_v2v_input.mp4",
    "strength": 0.85
  }'

Output

{
  "request_id": "hunyuan-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
Try Now

Webhook (Optional)

Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - Hunyuan Video (Video to Video) generate request

Parameter Required Type Default Allowed values / range Description
promptYesstring——The prompt to guide video transformation. Must describe the desired visual changes to the input video.
video_urlYesstring——Publicly accessible URL of the input video file to be transformed. Must be reachable by the Pixazo service.
strengthNofloat0.850.0 to 1.0Strength for video-to-video transformation. Higher values follow the prompt more closely.
seedNointeger——Seed for reproducibility. Use the same seed to generate identical results from the same input and prompt.
pro_modeNobooleanfalse—Enables higher quality generation using 55 steps instead of 35. Uses 2x billing units.
aspect_ratioNostring"16:9""16:9", "9:16"Output video aspect ratio.
resolutionNostring"720p""480p", "580p", "720p"Output video resolution.
num_framesNostring"129""129", "85"Number of frames in the output video.
enable_safety_checkerNobooleantrue—Toggle the safety checker to filter inappropriate content. When enabled, may block generation of unsafe outputs.

Example Request

{
  "prompt": "A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage. She wears a dark blue leather jacket, a long pink dress, and bright yellow boots, and carries a black purse.",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "num_frames": 129,
  "enable_safety_checker": true,
  "video_url": "https://example.com/hunyuan_video/hunyuan_v2v_input.mp4",
  "strength": 0.85
}

Response

{
  "request_id": "hunyuan-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Request Headers

Header Value
Content-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYOUR_API_KEY

Response Handling

Common status codes.

CodeMeaning
202Accepted — Request queued
Bad Request
401Unauthorized
402Insufficient Balance
403Forbidden
Too Many Requests
500Internal Server Error

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}
// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'hunyuan-video-video-to-video' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "hunyuan-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-video-video-to-video",
  "error": "Description of the error",
  "output": null
}

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

cURL Example

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/hunyuan-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response (Completed)

{
  "request_id": "hunyuan-video-video-to-video_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-video-video-to-video",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-video-video-to-video_019dxxxx/output.mp4"],
    "media_type": "video/mp4"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

FieldTypeDescription
request_idstringUnique request identifier
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR
model_idstringModel that processed the request
errorstring|nullError message if failed
output.media_urlarrayURLs to generated media (R2 CDN)
output.media_typestringMIME type of the output
created_atstringWhen request was created
completed_atstringWhen request completed
polling_urlstringStatus URL (initial response only)

Status Values

StatusDescription
QUEUEDRequest accepted, waiting to be processed
PROCESSINGBeing processed by the model
COMPLETEDDone — output contains the result
FAILEDFailed — check error field
ERRORSystem error — not charged

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

  1. Send a generate request to the API endpoint
  2. Save the request_id from the response
  3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
  4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.

Hunyuan Video v1 Video to Video (Video Editing) API Pricing

No data available

Could not load current pricing