# Hunyuan Video API

> Provider: **Tencent**
> Source: https://www.pixazo.ai/models/hunyuan-video

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

## Hunyuan Video v1

### Text to Video

## Base URL

```
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

### Image to Video

## Base URL

```
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

HTTP Python JavaScript cURL

```
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](https://api.pixazo.ai/api-details#api=hunyuan-video-image-to-video&operation=hunyuan-video-image-to-video-request)

## 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

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

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

HTTP Python JavaScript cURL

```
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](https://api.pixazo.ai/api-details#api=hunyuan-video-image-to-video&operation=hunyuan-video-image-to-video-request-result)

## 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

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

429

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.

### Video to Video (Video Editing)

## Base URL

```
https://gateway.pixazo.ai/hunyuan-video-video-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 (Video to Video) generate request

## Request Code

HTTP Python JavaScript cURL

```
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](https://api.pixazo.ai/api-details#api=hunyuan-video-video-to-video&operation=hunyuan-video-video-to-video-request)

## 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

prompt

Yes

string

—

—

The prompt to guide video transformation. Must describe the desired visual changes to the input video.

video\_url

Yes

string

—

—

Publicly accessible URL of the input video file to be transformed. Must be reachable by the Pixazo service.

strength

No

float

0.85

0.0 to 1.0

Strength for video-to-video transformation. Higher values follow the prompt more closely.

seed

No

integer

—

—

Seed for reproducibility. Use the same seed to generate identical results from the same input and prompt.

pro\_mode

No

boolean

false

—

Enables higher quality generation using 55 steps instead of 35. Uses 2x billing units.

aspect\_ratio

No

string

"16:9"

"16:9", "9:16"

Output video aspect ratio.

resolution

No

string

"720p"

"480p", "580p", "720p"

Output video resolution.

num\_frames

No

string

"129"

"129", "85"

Number of frames in the output video.

enable\_safety\_checker

No

boolean

true

—

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-Type

application/json

Cache-Control

no-cache

Ocp-Apim-Subscription-Key

YOUR\_API\_KEY

## Response Handling

Common status codes.

Code

Meaning

202

Accepted — Request queued

400

Bad Request

401

Unauthorized

402

Insufficient Balance

403

Forbidden

429

Too Many Requests

500

Internal 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

Field

Type

Description

request\_id

string

Unique request identifier

status

string

QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR

model\_id

string

Model that processed the request

error

string|null

Error message if failed

output.media\_url

array

URLs to generated media (R2 CDN)

output.media\_type

string

MIME type of the output

created\_at

string

When request was created

completed\_at

string

When request completed

polling\_url

string

Status URL (initial response only)

## Status Values

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

ERROR

System 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.