# Hunyuan V3

> Infographic-friendly generation with readable text and cfg control.

## Overview

- **Model ID**: `hunyuan-v3`
- **Workflow**: `hunyuan-image/v3/text-to-image`
- **Provider**: Hunyuan
- **Origin**: Partner Model
- **Category**: Text → Image (image)
- **Output**: One or more image URLs.
- **Tags**: 1k
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/hunyuan-image/v3/text-to-image/execute` (vendor's own parameters)
- **Execution**: sync (`/execute`) returns the result in one call; async is also available
- **Model page**: https://picsart.com/api-platform/models/hunyuan-v3

## Pricing

Live pricing for this model is not published yet. See https://picsart.com/pricing/ or the Pricing tab of the model page (https://picsart.com/api-platform/models/hunyuan-v3#pricing).

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK (TypeScript)** — `@picsart/ai-sdk` (Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **SDK (Python)** — `picsart-ai-sdk` (Python 3.10+, async). The same surface in snake_case: `await ai.generate()` / `await ai.generate_text()`, with a typed input per model.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK (TypeScript)
pip install picsart-ai-sdk       # SDK (Python)
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('hunyuan-v3', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

### Input parameters

- **`prompt`** (`string`, _required_): What to make, in plain language: the subject, style and composition. With an input image or video, what to change.
- **`aspectRatio`** (`string`, _optional_): Shape of the output as width:height. An auto or adaptive option follows the input image.
  - Default: `"16:9"`
  - Options: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`
- **`count`** (`number`, _optional_): How many results to make in one call. Each one is charged.
  - Default: `1`
  - Options: `1`, `2`, `4`
- **`negativePrompt`** (`string`, _optional_): What to keep out of the result, such as text, watermarks or blur.
- **`cfgScale`** (`number`, _optional_): How closely the result follows the prompt. Higher is stricter, lower more creative.
  - Default: `7.5`
  - Range: 1–20 (step 0.5)

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "description": "What to make, in plain language: the subject, style and composition. With an input image or video, what to change."
    },
    "aspectRatio": {
      "type": "string",
      "enum": [
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4"
      ],
      "default": "16:9",
      "description": "Shape of the output as width:height. An auto or adaptive option follows the input image."
    },
    "count": {
      "type": "number",
      "enum": [
        1,
        2,
        4
      ],
      "default": 1,
      "description": "How many results to make in one call. Each one is charged."
    },
    "negativePrompt": {
      "type": "string",
      "description": "What to keep out of the result, such as text, watermarks or blur."
    },
    "cfgScale": {
      "type": "number",
      "minimum": 1,
      "maximum": 20,
      "multipleOf": 0.5,
      "default": 7.5,
      "description": "How closely the result follows the prompt. Higher is stricter, lower more creative."
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "hunyuan-v3",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "aspectRatio": "16:9"
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Asset models return `url` plus an `items` array of results.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "url": "https://cdn.picsart.com/…/result",
      "items": [
        {
          "url": "https://cdn.picsart.com/…/result"
        }
      ],
      "model": "hunyuan-v3"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "items": [
    {
      "url": "https://cdn.picsart.com/…/result"
    }
  ],
  "model": "hunyuan-v3"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const result = await ai.generate('hunyuan-v3', {
  prompt: "A serene mountain lake at golden hour, ultra detailed",
  aspectRatio: "16:9"
});

console.log(result.url); // image URL
```

#### Python (SDK)

```python
import asyncio
import os

from picsart_ai_sdk import create_client


async def main() -> None:
    async with create_client(
        api_key=os.environ["PICSART_API_KEY"],
        api_url="https://api.picsart.com",
    ) as ai:
        result = await ai.generate("hunyuan-v3", {
            "prompt": "A serene mountain lake at golden hour, ultra detailed",
            "aspectRatio": "16:9",
        })

        print(result.url)  # image URL


asyncio.run(main())
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "hunyuan-v3",
    "params": {
      "prompt": "A serene mountain lake at golden hour, ultra detailed",
      "aspectRatio": "16:9"
    }
  }
}'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info hunyuan-v3  # this model's parameters
gen-ai pricing hunyuan-v3  # quote before spending credits
gen-ai generate -m hunyuan-v3 \
  -p "A serene mountain lake at golden hour" \
  --ar 16:9
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `hunyuan-image/v3/text-to-image` workflow takes Hunyuan's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/hunyuan-image/v3/text-to-image/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('hunyuan-image/v3/text-to-image', params, { mode })` in TypeScript, `ai.apis.run("hunyuan-image/v3/text-to-image", params, mode=…)` in Python — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `output_format` | `string` | no | `png` | The format of the generated image. · Options: `jpeg`, `png` |
| `image_size` | `ImageSize \| string` | no | `square_hd` | The desired size of the generated image. |
| `prompt` | `string` | yes | — | The text prompt for image-to-image. · e.g. `200mm telephoto through crowd gaps; subject laughing, candid; creamy background compression, color pop from a single bold garment, catchlight in eyes.` |
| `num_inference_steps` | `integer` | no | `28` | Number of denoising steps. · 1–50 |
| `num_images` | `integer` | no | `1` | The number of images to generate. · 1–4 |
| `enable_prompt_expansion` | `boolean` | no | `false` | Whether to enable prompt expansion. This will use a large language model to expand the prompt with additional details while maintaining the original meaning. · e.g. `true` |
| `negative_prompt` | `string` | no | — | The negative prompt to guide the image generation away from certain concepts. · e.g. `blurry, low quality, watermark, signature` |
| `seed` | `integer` | no | — | Random seed for reproducible results. If None, a random seed is used. |
| `enable_safety_checker` | `boolean` | no | `true` | If set to true, the safety checker will be enabled. Disabling it requires account authorization; unauthorized requests are always checked. |
| `sync_mode` | `boolean` | no | `false` | If `True`, the media will be returned as a data URI and the output data won't be available in the request history. |
| `guidance_scale` | `number` | no | `7.5` | Controls how much the model adheres to the prompt. Higher values mean stricter adherence. · 1–20 |
| `options` | `object` | no | — | Platform-specific options for safety checks and Picsart Drive integration. |
| └ `safety_checks` | `object` | no | — | Safety check configuration. |
| └   `enabled` | `boolean` | no | `true` | Enable or disable text safety checks. Defaults to true. |
| └ `drive` | `object` | no | — | Picsart Drive storage options. When provided, the result will be saved to the user's Drive. |
| └   `name` | `string` | yes | — | Filename to save the result as in Picsart Drive. |
| └   `attributes` | `object` | no | — | Additional file metadata attributes. |
| └   `folder` | `object` | no | — | Destination folder in Picsart Drive. |

### Example request body

```json
{
  "params": {
    "prompt": "200mm telephoto through crowd gaps; subject laughing, candid; creamy background compression, color pop from a single bold garment, catchlight in eyes."
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'hunyuan-image/v3/text-to-image' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('hunyuan-image/v3/text-to-image', {
  prompt: "200mm telephoto through crowd gaps; subject laughing, candid; creamy background compression, color pop from a single bold garment, catchlight in eyes."
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### Python (`ai.apis.run`)

```python
import asyncio
import os

from picsart_ai_sdk import ApiRunMode, create_client


async def main() -> None:
    async with create_client(
        api_key=os.environ["PICSART_API_KEY"],
        api_url="https://api.picsart.com",
    ) as ai:
        # Calls the 'hunyuan-image/v3/text-to-image' workflow directly — params are sent as-is.
        response = await ai.apis.run("hunyuan-image/v3/text-to-image", {
            "prompt": "200mm telephoto through crowd gaps; subject laughing, candid; creamy background compression, color pop from a single bold garment, catchlight in eyes.",
        }, mode=ApiRunMode.SYNC)

        print(response["result"])  # workflow-specific output
        print((response.get("usage") or {}).get("credits"))  # amount charged, in $


asyncio.run(main())
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/hunyuan-image/v3/text-to-image/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "prompt": "200mm telephoto through crowd gaps; subject laughing, candid; creamy background compression, color pop from a single bold garment, catchlight in eyes."
  }
}'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "id": "wf_abc123",
    "status": "COMPLETED",
    "result": {
      "images": [
        {
          "url": "https://v3b.fal.media/files/b/kangaroo/uIKrZHT6LaGqgXoxtBSn7.png",
          "content_type": "image/png"
        }
      ],
      "seed": 0
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "images": [
      {
        "url": "https://v3b.fal.media/files/b/kangaroo/uIKrZHT6LaGqgXoxtBSn7.png",
        "content_type": "image/png"
      }
    ],
    "seed": 0
  }
}
```

## Additional resources

- Model page (playground): https://picsart.com/api-platform/models/hunyuan-v3
- SDK and REST API (unified): https://picsart.com/api-platform/models/hunyuan-v3#api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/hunyuan-v3#advanced
- Pricing: https://picsart.com/api-platform/models/hunyuan-v3#pricing
- This document: https://picsart.com/api-platform/models/hunyuan-v3/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction