Hunyuan 3.0 3D API: Pricing, Documentation

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

WELCOME BONUS

Get $5 Free Credit on First Payment

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

Claim Your $5 →

Hunyuan3D 3.1 Pro API Documentation

https://gateway.pixazo.ai/hunyuan-3d/v1/hunyuan-3d-request

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.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

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	—	≤ 200 UTF-8 characters	Text description of the 3D content to generate. Max 200 UTF-8 characters.
enable_pbr	No	boolean	false	—	Enable PBR material generation (metallic, roughness, and normal textures) for realistic surface lighting. Has no effect when enable_geometry is true.
enable_geometry	No	boolean	false	—	Generate a geometry-only white model without textures. When enabled, enable_pbr is ignored and OBJ output is not supported (default output is GLB).

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 API Pricing

Your request will cost $0.225 per generated 3D model.

Image to Image (3D Models — Image to 3D)

Hunyuan3D 3.1 Pro API Documentation

https://gateway.pixazo.ai/hunyuan-3d-v3-1-pro-image-to-3d/v1/hunyuan-3d-v3-1-pro-image-to-3d-request

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	—	JPG/PNG/WEBP URL; ≤ 8 MB; 128–5000 px	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	—	image URL; ≤ 8 MB	Optional back/rear view image URL (JPG/PNG recommended).
left_image_url	No	string	—	image URL; ≤ 8 MB	Optional left side view image URL (JPG/PNG recommended).
right_image_url	No	string	—	image URL; ≤ 8 MB	Optional right side view image URL (JPG/PNG recommended).
top_image_url	No	string	—	image URL; ≤ 8 MB	Optional top view image URL (v3.1 exclusive, JPG/PNG recommended).
bottom_image_url	No	string	—	image URL; ≤ 8 MB	Optional bottom view image URL (v3.1 exclusive, JPG/PNG recommended).
left_front_image_url	No	string	—	image URL; ≤ 8 MB	Optional left-front 45 degree angle view image URL (v3.1 exclusive, JPG/PNG recommended).
right_front_image_url	No	string	—	image URL; ≤ 8 MB	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	false	—	Generates realistic surface materials (PBR: metallic, roughness, and normal maps) so the 3D model reacts properly to light. Ignored for geometry-only output.
face_count	No	integer	500000	40000–1500000	The target level of detail for the 3D model, measured in mesh faces (40,000-1,500,000). More faces mean finer detail but heavier files.

Content Item Types & Limits

Type	Max	Format / Size	Description
image	1	JPG, PNG, WEBP · < 8 MB	View image (front/back/side/top/bottom), 128–5000px.

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 API Pricing

Your request will cost $0.225 per generated 3D model.

2. Hunyuan3D 3.0

Hunyuan3D 3.0 API Documentation

https://gateway.pixazo.ai/hunyuan3d-3-0-api-294/v1/hunyuan3d-3-0-api-request

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	—	128x128–5000x5000 px, ≤ 8MB (jpg, jpeg, png, webp, gif, avif)	URL of the sketch or line-art image to transform into a 3D model. Image resolution must be between 128x128 and 5000x5000 pixels. Must be publicly accessible.
prompt	Yes	string	—	≤ 1024 chars	Text prompt describing the desired 3D content attributes such as color, category, and material.
enable_pbr	No	boolean	false	true, false	Generates realistic surface materials (PBR: metallic, roughness, and normal maps) so the 3D model reacts properly to light.
face_count	No	integer	500000	40000–1500000	The target level of detail for the 3D model, measured in mesh faces. More faces mean finer detail but a larger file and longer processing.

Content Item Types & Limits

Type	Max	Format / Size	Description
image	1	JPG, PNG, WEBP	Input image to convert to 3D.

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

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 API Pricing

Your request will cost $0.375 per generated 3D model.

3. Hunyuan Image 3.0

Hunyuan Image 3.0 API Documentation

https://gateway.pixazo.ai/hunyuan-image/v1/hunyuan-image/generateRequest

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	—	Number of refinement steps the model runs while generating. Higher values refine detail and quality but increase processing time; lower values are faster.
guidance_scale	No	float	7.5	—	Controls how closely the output follows your prompt (prompt adherence). Higher values stick more strictly to the prompt; lower values allow more creative variation.
seed	No	integer	null	—	Random seed that controls the generation's randomness. Reuse the same seed with identical settings to reproduce the same result; leave it empty for a different output each time.
enable_safety_checker	No	boolean	true	true, false	Default: true. Turns on automatic filtering of unsafe or explicit (NSFW) content. Leave enabled unless you have a specific reason to disable it.
sync_mode	No	boolean	null	true, false	If on, the finished file is sent back directly instead of as a download link. Handy for quick tests; for normal use, leave it off to get a download link.
output_format	No	string	png	—	Default: "png". The format of the generated image. Values: "jpeg", "png"
enable_prompt_expansion	No	boolean	null	true, false	Automatically rewrites and enriches your prompt with extra detail before generation to improve results.

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 API Pricing

Your request will cost $0.20 per image.

4. Hunyuan Image 3.0 Instruct

Hunyuan Image 3.0 Instruct API Documentation

https://gateway.pixazo.ai/hunyuan-image-3-0-instruct/v1/hunyuan-image-3-0-instruct-request

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 or object	auto	"auto", "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9", or {width, height}	Target output size. Accepts a preset ("auto", "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9") or a custom {width, height} object (each dimension up to 14142 px). When set to "auto", the model determines the image size.
num_images	No	integer	1	1–4	Number of images to generate per request. Must be between 1 and 4.
guidance_scale	No	number	3.5	up to 20	Controls how closely the output follows your prompt (prompt adherence). Higher values stick more strictly to the prompt; lower values allow more creative variation. Maximum value is 20.
enable_prompt_expansion	No	boolean	true	true, false	When enabled, the prompt is expanded through the model's internal recaptioning step to add detail and context. Disable for a more literal interpretation of your prompt.
enable_safety_checker	No	boolean	true	true, false	Turns on automatic filtering of unsafe or explicit (NSFW) content. Leave enabled unless you have a specific reason to disable it.
output_format	No	string	png	jpeg, png	Output image format. Accepts "jpeg" or "png".
seed	No	integer	—	—	Optional random seed for reproducible results. Use the same seed with identical inputs to reproduce an output; if omitted, a random seed is used.
sync_mode	No	boolean	false	true, false	If true, the generated image(s) are returned inline as base64-encoded data URIs in the response instead of hosted URLs (and won't appear in request history). If false, a request_id is returned for asynchronous polling.

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

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 API Pricing

Your request will cost $0.09 per image.

Image to Image (Image Editing)

Hunyuan Image 3.0 Instruct API Documentation

https://gateway.pixazo.ai/hunyuan-image-v3-instruct-edit/v1/hunyuan-image-v3-instruct-edit-request

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 v3 Instruct Edit generate request

Request Code

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

{
  "prompt": "Change the background to a snowy alpine landscape at sunset",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
  ],
  "image_size": "auto",
  "num_images": 1,
  "guidance_scale": 3.5,
  "enable_prompt_expansion": true,
  "enable_safety_checker": true,
  "output_format": "png",
  "sync_mode": false
}

import requests

url = "https://gateway.pixazo.ai/hunyuan-image-v3-instruct-edit/v1/hunyuan-image-v3-instruct-edit-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "Change the background to a snowy alpine landscape at sunset",
    "image_urls": [
        "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
    ],
    "image_size": "auto",
    "num_images": 1,
    "guidance_scale": 3.5,
    "enable_prompt_expansion": true,
    "enable_safety_checker": true,
    "output_format": "png",
    "sync_mode": false
}

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

const url = "https://gateway.pixazo.ai/hunyuan-image-v3-instruct-edit/v1/hunyuan-image-v3-instruct-edit-request";

const data = {
  prompt: "Change the background to a snowy alpine landscape at sunset",
  image_urls: [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
  ],
  image_size: "auto",
  num_images: 1,
  guidance_scale: 3.5,
  enable_prompt_expansion: true,
  enable_safety_checker: true,
  output_format: "png",
  sync_mode: false
};

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-image-v3-instruct-edit/v1/hunyuan-image-v3-instruct-edit-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "Change the background to a snowy alpine landscape at sunset",
    "image_urls": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg"
    ],
    "image_size": "auto",
    "num_images": 1,
    "guidance_scale": 3.5,
    "enable_prompt_expansion": true,
    "enable_safety_checker": true,
    "output_format": "png",
    "sync_mode": false
  }'

Output

{
  "request_id": "hunyuan-image-v3-instruct-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-image-v3-instruct-edit_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 Image v3 Instruct Edit generate request

Parameter	Required	Type	Default	Allowed values / range	Description
prompt	Yes	string	—	—	Text prompt describing the desired edit. Must be detailed and specific for best results.
image_urls	Yes	string[]	—	—	Array of URLs pointing to reference images. Maximum of 3 images allowed. All images must be publicly accessible.
image_size	No	string or object	"auto"	"auto", "square_hd", "square", "portrait_4_3", "portrait_16_9", "landscape_4_3", "landscape_16_9", or {width, height}	Preset aspect ratios: `auto`, `square_hd`, `square`, `portrait_4_3`, `portrait_16_9`, `landscape_4_3`, `landscape_16_9`. Alternatively, provide a custom object with `width` and `height` (e.g., `{\"width\": 1024, \"height\": 768}`).
num_images	No	integer	1	1–4	Number of images to generate. Must be between 1 and 4 inclusive.
guidance_scale	No	float	3.5	up to 20	Controls how closely the output adheres to the prompt. Higher values increase prompt fidelity but may reduce creativity. Maximum value is 20.
enable_prompt_expansion	No	boolean	true	—	Enables LLM-based expansion of the prompt to enhance detail and context. Disable for minimal interpretation.
enable_safety_checker	No	boolean	true	—	Enables NSFW content filtering. Disabling may expose outputs to inappropriate content.
output_format	No	string	"png"	"jpeg", "png"	Output image format. Allowed values: `jpeg`, `png`.
seed	No	integer	—	—	Optional random seed for reproducible results. Use the same seed with identical inputs to generate identical outputs.
sync_mode	No	boolean	false	—	If `true`, returns the generated image(s) as base64-encoded data URIs inline in the response. If `false`, returns a `request_id` for asynchronous polling.

Content Item Types & Limits

Type	Max	Format / Size	Description
image	—	JPG, PNG, WEBP	Reference image(s) to edit.

Example Request

{
  "prompt": "Change the background to a snowy alpine landscape at sunset",
  "image_urls": [
    "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/nano-banana/nano-banana-a382a80b-f8df-4de1-a0c1-a5dcfd42dae4-1758783383399.jpg"
  ],
  "image_size": "auto",
  "num_images": 1,
  "guidance_scale": 3.5,
  "enable_prompt_expansion": true,
  "enable_safety_checker": true,
  "output_format": "png",
  "sync_mode": false
}

Response

{
  "request_id": "hunyuan-image-v3-instruct-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/hunyuan-image-v3-instruct-edit_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-image-v3-instruct-edit' not found or is disabled"
}

Error via Status/Webhook

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

Response (Completed)

{
  "request_id": "hunyuan-image-v3-instruct-edit_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "hunyuan-image-v3-instruct-edit",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/hunyuan-image-v3-instruct-edit_019dxxxx/output.png"
    ],
    "media_type": "image/png"
  },
  "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.

Hunyuan Image 3.0 Instruct API Pricing

Your request will cost $0.10 per generated 3D model.