Hunyuan 3.0 3D API - AI Image & 3D Model Generation APIs

Hunyuan 3.0 3D API, developers can access Hunyuan's capabilities for generating detailed images and converting them into 3D models. The API leverages Tencent's extensive AI research to deliver high-quality outputs suitable for gaming, virtual worlds, and digital content production.

Get API Key

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 →

Hunyuan3D 3.1 Pro Text to Image (3D Models — Text to 3D) API Documentation

https://gateway.pixazo.ai/hunyuan-3d/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

Text to 3D Request - Hunyuan3D 3.1

Request Code

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

{
  "prompt": "A medieval stone castle tower with moss-covered walls and a spiral staircase"
}

import requests

url = "https://gateway.pixazo.ai/hunyuan-3d/v1/hunyuan-3d-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A medieval stone castle tower with moss-covered walls and a spiral staircase"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const url = 'https://gateway.pixazo.ai/hunyuan-3d/v1/hunyuan-3d-request';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
};
const data = {
  prompt: 'A medieval stone castle tower with moss-covered walls and a spiral staircase'
};

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-3d/v1/hunyuan-3d-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A medieval stone castle tower with moss-covered walls and a spiral staircase"
  }'

Output

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

Try Now

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Webhook Headers

Header	Required	Default	Description
`X-Webhook-URL`	Yes (to enable)	—	HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).
`X-Webhook-Mode`	No	`terminal`	`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates.

Example: enable webhook

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

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "hunyuan-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-3d",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "hunyuan-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-3d",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
HTTPS required — plain http:// URLs are rejected.

Request Parameters - Text to 3D Request

Parameter	Required	Type	Default	Allowed values / range	Description
prompt	Yes	string	—	—	Text description of the 3D scene/object to generate

Example Request

{
  "prompt": "A medieval stone castle tower with moss-covered walls and a spiral staircase"
}

Response

{
  "request_id": "hunyuan-3d_019exxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-3d_019exxxx-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-3d' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "hunyuan-3d_019exxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-3d",
  "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-3d_019exxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response (Completed)

{
  "request_id": "hunyuan-3d_019exxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-3d",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-3d_019exxxx-xxxx/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\|null	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

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

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

Hunyuan3D 3.1 Pro Text to Image (3D Models — Text to 3D) API Pricing

Resolution	Price (USD)
Per generation	$0.225

Hunyuan3D 3.1 Pro Image to Image (3D Models — Image to 3D) API Documentation

https://gateway.pixazo.ai/hunyuan-3d-v3-1-pro-image-to-3d/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 3D V3.1 Pro Image to 3D generate request

Request Code

POST https://gateway.pixazo.ai/hunyuan-3d-v3-1-pro-image-to-3d/v1/hunyuan-3d-v3-1-pro-image-to-3d-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/input_model.png",
  "generate_type": "Normal",
  "enable_pbr": true,
  "face_count": 500000
}

import requests

url = "https://gateway.pixazo.ai/hunyuan-3d-v3-1-pro-image-to-3d/v1/hunyuan-3d-v3-1-pro-image-to-3d-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/input_model.png",
    "generate_type": "Normal",
    "enable_pbr": true,
    "face_count": 500000
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const url = "https://gateway.pixazo.ai/hunyuan-3d-v3-1-pro-image-to-3d/v1/hunyuan-3d-v3-1-pro-image-to-3d-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/input_model.png",
  "generate_type": "Normal",
  "enable_pbr": true,
  "face_count": 500000
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

curl -X POST "https://gateway.pixazo.ai/hunyuan-3d-v3-1-pro-image-to-3d/v1/hunyuan-3d-v3-1-pro-image-to-3d-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/input_model.png",
    "generate_type": "Normal",
    "enable_pbr": true,
    "face_count": 500000
  }'

Output

{
  "request_id": "hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Try Now

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Webhook Headers

Header	Required	Default	Description
`X-Webhook-URL`	Yes (to enable)	—	HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).
`X-Webhook-Mode`	No	`terminal`	`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates.

Example: enable webhook

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

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-3d-v3-1-pro-image-to-3d",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.glb"
    ],
    "media_type": "model/glb"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-3d-v3-1-pro-image-to-3d",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
HTTPS required — plain http:// URLs are rejected.

Request Parameters - Hunyuan 3D V3.1 Pro Image to 3D generate request

Parameter	Required	Type	Default	Allowed values / range	Description
input_image_url	Yes	string	—	non-empty; ≤ 5000 chars	Front view image URL. Resolution: 128-5000px, max 8MB, formats: JPG/PNG/WEBP. Tips: simple background, single object, object >50% of frame.
back_image_url	No	string	—	non-empty; ≤ 5000 chars	Optional back/rear view image URL (JPG/PNG recommended).
left_image_url	No	string	—	non-empty; ≤ 5000 chars	Optional left side view image URL (JPG/PNG recommended).
right_image_url	No	string	—	non-empty; ≤ 5000 chars	Optional right side view image URL (JPG/PNG recommended).
top_image_url	No	string	—	non-empty; ≤ 5000 chars	Optional top view image URL (v3.1 exclusive, JPG/PNG recommended).
bottom_image_url	No	string	—	non-empty; ≤ 5000 chars	Optional bottom view image URL (v3.1 exclusive, JPG/PNG recommended).
left_front_image_url	No	string	—	non-empty; ≤ 5000 chars	Optional left-front 45 degree angle view image URL (v3.1 exclusive, JPG/PNG recommended).
right_front_image_url	No	string	—	non-empty; ≤ 5000 chars	Optional right-front 45 degree angle view image URL (v3.1 exclusive, JPG/PNG recommended).
generate_type	No	enum	"Normal"	"Normal", "Geometry"	Generation task type. Allowed: Normal (textured model), Geometry (geometry-only white model, no textures). LowPoly/Sketch not available in v3.1.
enable_pbr	No	boolean	true	—	Enable PBR material generation (metallic, roughness, normal textures). Ignored when generate_type is Geometry.
face_count	No	integer	500000	40000–1500000	Target polygon face count. Range: 40,000 - 1,500,000.

Example Request

{
  "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/input_model.png",
  "generate_type": "Normal",
  "enable_pbr": true,
  "face_count": 500000
}

Response

{
  "request_id": "hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-3d-v3-1-pro-image-to-3d_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-3d-v3-1-pro-image-to-3d' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-3d-v3-1-pro-image-to-3d",
  "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-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response (Completed)

{
  "request_id": "hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-3d-v3-1-pro-image-to-3d",
  "error": null,
  "output": {
    "model_glb": {
      "file_name": "model.glb",
      "url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx/model.glb",
      "file_size": 2457600,
      "content_type": "model/gltf-binary"
    },
    "thumbnail": {
      "file_name": "thumbnail.png",
      "url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx/thumbnail.png",
      "file_size": 102400,
      "content_type": "image/png"
    },
    "model_urls": {
      "obj": {
        "file_name": "model.obj",
        "url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx/model.obj",
        "file_size": 1843200,
        "content_type": "model/obj"
      },
      "glb": {
        "file_name": "model.glb",
        "url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-3d-v3-1-pro-image-to-3d_019dxxxx/model.glb",
        "file_size": 2457600,
        "content_type": "model/gltf-binary"
      }
    }
  },
  "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

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

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

Hunyuan3D 3.1 Pro Image to Image (3D Models — Image to 3D) API Pricing

Resolution	Price (USD)
Per generation	$0.225

2. Hunyuan3D 3.0

Hunyuan3D 3.0 Image to Image (3D Models — Image to 3D) API Documentation

https://gateway.pixazo.ai/hunyuan3d-3-0-api-294/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

Hunyuan3D 3.0 API generate request - Hunyuan 3D 3.0 API

Request Code

POST https://gateway.pixazo.ai/hunyuan3d-3-0-api-294/v1/hunyuan3d-3-0-api-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/cat-vector.png",
  "prompt": "orange cat",
  "face_count": 500000
}

import requests

url = "https://gateway.pixazo.ai/hunyuan3d-3-0-api-294/v1/hunyuan3d-3-0-api-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/cat-vector.png",
    "prompt": "orange cat",
    "face_count": 500000
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const url = 'https://gateway.pixazo.ai/hunyuan3d-3-0-api-294/v1/hunyuan3d-3-0-api-request';

const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};

const data = {
  input_image_url: 'https://pub-582b7213209642b9b995c96c95a30381.r2.dev/cat-vector.png',
  prompt: 'orange cat',
  face_count: 500000
};

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/hunyuan3d-3-0-api-294/v1/hunyuan3d-3-0-api-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/cat-vector.png",
    "prompt": "orange cat",
    "face_count": 500000
  }'

Output

{
  "request_id": "hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Try Now

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Webhook Headers

Header	Required	Default	Description
`X-Webhook-URL`	Yes (to enable)	—	HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).
`X-Webhook-Mode`	No	`terminal`	`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates.

Example: enable webhook

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

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan3d-3-0-api-294",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.glb"
    ],
    "media_type": "model/glb"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan3d-3-0-api-294",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
HTTPS required — plain http:// URLs are rejected.

Request Parameters - Hunyuan3D 3.0 API generate request

Parameter	Required	Type	Default	Allowed values / range	Description
input_image_url	Yes	string	—	—	URL of the input image or sketch to convert into a 3D model. Must be publicly accessible.
prompt	No	string	"" (empty string)	—	Text prompt to guide the 3D generation process. Used to refine or enhance the model when an image is provided.
face_count	No	integer	500000	—	Target number of polygon faces in the output 3D mesh. Higher values yield higher detail but longer processing times.

Minimum Request

{
  "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/cat-vector.png"
}

Full Request (all options)

{
  "input_image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/cat-vector.png",
  "prompt": "orange cat",
  "face_count": 500000
}

Response

{
  "request_id": "hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Request Headers

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

Response Handling

Common status codes for Hunyuan3D 3.0 API generate request.

Code	Meaning
202	Accepted — Request queued
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error

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 'hunyuan3d-3-0-api-294' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan3d-3-0-api-294",
  "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/hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response (Completed)

{
  "request_id": "hunyuan3d-3-0-api-294_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan3d-3-0-api-294",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan3d-3-0-api-294_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "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\|null	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

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

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

Hunyuan3D 3.0 Image to Image (3D Models — Image to 3D) API Pricing

Resolution	Price (USD)
Normal	$0.375

3. Hunyuan Image 3.0

Hunyuan Image 3.0 Text to Image API Documentation

https://gateway.pixazo.ai/hunyuan-image/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

Generate image request - Hunyuan Image API

Request Code

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

{
  "prompt": "A vibrant sunflower field at golden hour, with bees hovering above, soft wind rustling petals, ultra-detailed, photorealistic",
  "negative_prompt": "blurry, cartoon, low quality, watermark",
  "image_size": "landscape_16_9",
  "num_images": 1,
  "num_inference_steps": 28,
  "guidance_scale": 7.5,
  "enable_safety_checker": true,
  "output_format": "png",
  "enable_prompt_expansion": true
}

import requests
import json

url = "https://gateway.pixazo.ai/hunyuan-image/v1/hunyuan-image/generateRequest"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A vibrant sunflower field at golden hour, with bees hovering above, soft wind rustling petals, ultra-detailed, photorealistic",
    "negative_prompt": "blurry, cartoon, low quality, watermark",
    "image_size": "landscape_16_9",
    "num_images": 1,
    "num_inference_steps": 28,
    "guidance_scale": 7.5,
    "enable_safety_checker": true,
    "output_format": "png",
    "enable_prompt_expansion": true
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const url = 'https://gateway.pixazo.ai/hunyuan-image/v1/hunyuan-image/generateRequest';
const headers = {
  'Content-Type': 'application/json',
  'Cache-Control': 'no-cache',
  'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
};
const body = {
  prompt: 'A vibrant sunflower field at golden hour, with bees hovering above, soft wind rustling petals, ultra-detailed, photorealistic',
  negative_prompt: 'blurry, cartoon, low quality, watermark',
  image_size: 'landscape_16_9',
  num_images: 1,
  num_inference_steps: 28,
  guidance_scale: 7.5,
  enable_safety_checker: true,
  output_format: 'png',
  enable_prompt_expansion: true
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(body)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

curl -v -X POST "https://gateway.pixazo.ai/hunyuan-image/v1/hunyuan-image/generateRequest" \
-H "Content-Type: application/json" \
-H "Cache-Control: no-cache" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-raw '{
  "prompt": "A vibrant sunflower field at golden hour, with bees hovering above, soft wind rustling petals, ultra-detailed, photorealistic",
  "negative_prompt": "blurry, cartoon, low quality, watermark",
  "image_size": "landscape_16_9",
  "num_images": 1,
  "num_inference_steps": 28,
  "guidance_scale": 7.5,
  "enable_safety_checker": true,
  "output_format": "png",
  "enable_prompt_expansion": true
}'

Output

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

Try Now

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Webhook Headers

Header	Required	Default	Description
`X-Webhook-URL`	Yes (to enable)	—	HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).
`X-Webhook-Mode`	No	`terminal`	`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates.

Example: enable webhook

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

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "hunyuan-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "hunyuan-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-image",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
HTTPS required — plain http:// URLs are rejected.

Request Parameters - Generate image request

Parameter	Required	Type	Default	Allowed values / range	Description
prompt	Yes	string	—	—	The text prompt for image generation
negative_prompt	No	string	:	—	Default: "". The negative prompt to guide the image generation away from certain concepts
image_size	No	string	square_hd	—	Default: "square_hd". The desired size of the generated image. Available values: "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9"
num_images	No	integer	1	—	Default: 1. The number of images to generate. Max 4
num_inference_steps	No	integer	28	—	Default: 28. Number of denoising steps. Higher values result in higher quality images but take longer to generate
guidance_scale	No	float	7.5	—	Default: 7.5. Controls how much the model adheres to the prompt. Higher values mean stricter adherence
seed	No	integer	null	—	Default: null. Random seed for reproducible results. If None, a random seed is used
enable_safety_checker	No	boolean	true	true, false	Default: true. Whether to enable the safety checker to filter NSFW content
sync_mode	No	boolean	null	true, false	Default: null. If true, the media will be returned as a data URI and the output data won't be available in the request history
output_format	No	string	png	—	Default: "png". The format of the generated image. Values: "jpeg", "png"
enable_prompt_expansion	No	boolean	null	true, false	Default: null. Whether to enable prompt expansion using a large language model to expand the prompt with additional details

Example Request

{
  "prompt": "A vibrant sunflower field at golden hour, with bees hovering above, soft wind rustling petals, ultra-detailed, photorealistic",
  "negative_prompt": "blurry, cartoon, low quality, watermark",
  "image_size": "landscape_16_9",
  "num_images": 1,
  "num_inference_steps": 28,
  "guidance_scale": 7.5,
  "enable_safety_checker": true,
  "output_format": "png",
  "enable_prompt_expansion": true
}

Response

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

Request Headers

Header	Value
Content-Type	application/json
Cache-Control	no-cache
Ocp-Apim-Subscription-Key	Your subscription 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-image' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "hunyuan-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-image",
  "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-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response (Completed)

{
  "request_id": "hunyuan-image_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-image",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-image_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "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\|null	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

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

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

Hunyuan Image 3.0 Text to Image API Pricing

Resolution	Price (USD)
1024×1024	$0.2
768×768	$0.1125
1080×1440	$0.2968
1080×1920	$0.396
1440×1080	$0.2968
1920×1080	$0.396

4. Hunyuan Image 3.0 Instruct

Hunyuan Image 3.0 Instruct Text to Image API Documentation

https://gateway.pixazo.ai/hunyuan-image-3-0-instruct/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 Image 3.0 Instruct generate request - Hunyuan Image 3.0 Instruct

Request Code

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

{
  "prompt": "A detailed watercolor painting of a Japanese garden in autumn, with a red wooden bridge over a koi pond, falling maple leaves, and soft morning mist",
  "image_size": "auto",
  "num_images": 1,
  "guidance_scale": 3.5,
  "enable_safety_checker": true,
  "output_format": "png"
}

import requests

url = "https://gateway.pixazo.ai/hunyuan-image-3-0-instruct/v1/hunyuan-image-3-0-instruct-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
data = {
    "prompt": "A detailed watercolor painting of a Japanese garden in autumn, with a red wooden bridge over a koi pond, falling maple leaves, and soft morning mist",
    "image_size": "auto",
    "num_images": 1,
    "guidance_scale": 3.5,
    "enable_safety_checker": True,
    "output_format": "png"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const url = 'https://gateway.pixazo.ai/hunyuan-image-3-0-instruct/v1/hunyuan-image-3-0-instruct-request';

const data = {
  prompt: "A detailed watercolor painting of a Japanese garden in autumn, with a red wooden bridge over a koi pond, falling maple leaves, and soft morning mist",
  image_size: "auto",
  num_images: 1,
  guidance_scale: 3.5,
  enable_safety_checker: true,
  output_format: "png"
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache',
    'Ocp-Apim-Subscription-Key': 'YOUR_SUBSCRIPTION_KEY'
  },
  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-image-3-0-instruct/v1/hunyuan-image-3-0-instruct-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "prompt": "A detailed watercolor painting of a Japanese garden in autumn, with a red wooden bridge over a koi pond, falling maple leaves, and soft morning mist",
    "image_size": "auto",
    "num_images": 1,
    "guidance_scale": 3.5,
    "enable_safety_checker": true,
    "output_format": "png"
  }'

Output

{
  "request_id": "hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Try Now

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Webhook Headers

Header	Required	Default	Description
`X-Webhook-URL`	Yes (to enable)	—	HTTPS endpoint on your server that will receive the `POST` callback. Must respond `2xx` within a few seconds (process async if needed).
`X-Webhook-Mode`	No	`terminal`	`terminal` — fires once at the final status (`COMPLETED`/`FAILED`/`ERROR`). `sync` — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates.

Example: enable webhook

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

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-image-3-0-instruct",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-image-3-0-instruct",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
sync mode — POST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
HTTPS required — plain http:// URLs are rejected.

Request Parameters - Hunyuan Image 3.0 Instruct generate request

Parameter	Required	Type	Default	Allowed values / range	Description
prompt	Yes	string	—	—	A detailed textual description of the desired image. Use specific visual elements, styles, lighting, and composition for best results.
image_size	No	string	auto	—	Target output resolution. Accepts "auto", "512x512", "1024x1024", "768x1344", "1344x768".
num_images	No	integer	1	—	Number of images to generate per request. Maximum value is 4.
guidance_scale	No	number	3.5	—	Controls how closely the generated image follows the prompt. Values typically range from 1.0 to 10.0. Higher values increase prompt adherence but may reduce creativity.
enable_safety_checker	No	boolean	true	true, false	Enables content filtering to block inappropriate or harmful outputs. Disable only if you are certain your prompts are safe.
output_format	No	string	png	—	Output image format. Accepts "png", "jpeg", or "webp".

Minimum Request

{
  "prompt": "A detailed watercolor painting of a Japanese garden in autumn, with a red wooden bridge over a koi pond, falling maple leaves, and soft morning mist"
}

Full Request (all options)

{
  "prompt": "A detailed watercolor painting of a Japanese garden in autumn, with a red wooden bridge over a koi pond, falling maple leaves, and soft morning mist",
  "image_size": "auto",
  "num_images": 1,
  "guidance_scale": 3.5,
  "enable_safety_checker": true,
  "output_format": "png"
}

Response

{
  "request_id": "hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

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 Image 3.0 Instruct generate request.

Code	Meaning
202	Accepted — Request queued
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error

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-image-3-0-instruct' not found or is disabled"
}

Error via Status/Webhook

{
  "request_id": "hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "hunyuan-image-3-0-instruct",
  "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-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Response (Completed)

{
  "request_id": "hunyuan-image-3-0-instruct_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-image-3-0-instruct",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-image-3-0-instruct_019dxxxx-xxxx/output.ext"
    ],
    "media_type": "application/octet-stream"
  },
  "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\|null	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

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

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

Hunyuan Image 3.0 Instruct Text to Image API Pricing

No data available

Could not load current pricing