# Introduction
Source: https://docs.hoox.video/agent-tooling/index

Integrate Hoox into your AI agent via MCP or agent skills — generate videos, manage avatars and voices using natural language

## Overview

Hoox provides two ways to give your AI agent the ability to generate videos through natural language:

* **MCP Server** — add `https://app.hoox.video/api/mcp` as a connector in any MCP-compatible client (Claude, Claude Code, Cursor…) and sign in with your Hoox account. No API key to manage.
* **Agent Skills** — install a reusable skill into your coding assistant (Cursor, Claude Code…) so it knows how to call the Hoox API. Requires an **API key** from [app.hoox.video → Settings → API Keys](https://app.hoox.video).

Both approaches require a **Pro plan** or higher.

## Choose your approach

<CardGroup>
  <Card title="MCP Server" icon="server" href="/agent-tooling/mcp">
    The standard protocol for agents. Remote connector with OAuth sign-in — recommended for Claude, Claude Code, and Cursor.
  </Card>

  <Card title="Agent Skills" icon="bolt" href="/agent-tooling/skills">
    A lighter approach. Install a reusable skill package directly into your CLI or editor.
  </Card>
</CardGroup>

***

## Resources

<CardGroup>
  <Card title="API Documentation" icon="book" href="/quickstart">
    Full API reference and quick start guide
  </Card>

  <Card title="GitHub — Agent Skills" icon="github" href="https://github.com/hoox-video/skill">
    Agent skill source code and contribution guide
  </Card>
</CardGroup>


# MCP Server
Source: https://docs.hoox.video/agent-tooling/mcp

Connect Hoox to Claude, Cursor, and any MCP-compatible client — generate videos, manage avatars and voices using natural language

The official [Model Context Protocol](https://modelcontextprotocol.io) server for Hoox. Any MCP-compatible client can generate videos and assets, manage avatars and voices, and export MP4 files using natural language.

The server is hosted by Hoox — nothing to install and no API key to manage:

```text theme={null}
https://app.hoox.video/api/mcp
```

When your client connects for the first time, a browser window opens on app.hoox.video: sign in, choose the workspace to connect (if you belong to several), and click **Authorize**. Every tool then operates on that workspace and consumes its credits. To switch workspace, disconnect and reconnect.

<Info>
  A **Pro** plan or higher is required on the connected workspace.
</Info>

## Setup

### Claude (web, desktop and mobile)

1. Go to **Settings → Connectors → Add custom connector**
2. Paste `https://app.hoox.video/api/mcp` and confirm
3. Complete the sign-in flow when prompted

<Info>
  On Claude **Team** and **Enterprise** plans, an admin can add the connector once
  from the admin settings and make it available to the whole organization. Each
  member still signs in with their own Hoox account the first time they use it.
</Info>

### Claude Code

```bash theme={null}
claude mcp add --transport http hoox https://app.hoox.video/api/mcp
```

Then run `/mcp` inside Claude Code to authenticate.

### Cursor and other MCP clients

Add the server URL to your client's MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "hoox": {
      "url": "https://app.hoox.video/api/mcp"
    }
  }
}
```

## Example prompts

<Info>
  Hoox credits are required to use the MCP tools.
</Info>

<AccordionGroup>
  <Accordion title="Generate a full video">
    ```text theme={null}
    Use Hoox to generate a 60-second vertical product demo video for our new DTC skincare serum.
    Export the final video to MP4 and return the download URL.
    ```
  </Accordion>

  <Accordion title="List avatars and voices">
    ```text theme={null}
    List the male avatars available with a professional style.
    Also list female English voices with a conversational tag.
    ```
  </Accordion>

  <Accordion title="Create a custom avatar">
    ```text theme={null}
    Create an avatar from this description: man in a conference room in a suit.
    ```
  </Accordion>

  <Accordion title="Generate assets">
    ```text theme={null}
    Check the pricing, then generate 2 images of a skincare serum bottle on a
    marble bathroom shelf, morning light, and put them in a "Serum campaign" folder.
    ```
  </Accordion>

  <Accordion title="Duplicate a video">
    ```text theme={null}
    Duplicate the video vid_xxx by changing the voice to a male English voice,
    then export the result as MP4.
    ```
  </Accordion>

  <Accordion title="Full script-to-MP4 workflow">
    ```text theme={null}
    Generate a 45-second script about our new DTC skincare serum,
    then start the video generation and export the result as MP4.
    ```
  </Accordion>
</AccordionGroup>

## Available tools

#### Workspace

| Tool | Description |
| - | - |
| `get_space_info` | Get the connected workspace: name, plan and remaining credits |

#### Voices

| Tool | Description |
| - | - |
| `list_voices` | List available voices with optional filters (language, gender) |
| `get_voice` | Get full details for a voice by ID |

#### Avatars

| Tool | Description |
| - | - |
| `list_avatars` | List available avatar looks with optional metadata filters |
| `get_avatar` | Get full details for an avatar and its looks |
| `create_avatar` | Create a new avatar from a prompt or reference images |
| `edit_avatar` | Create a new look for an existing avatar |
| `get_avatar_status` | Check the generation status of an avatar look |

#### Folders

| Tool | Description |
| - | - |
| `list_folders` | List the workspace's asset and video folders |
| `create_folder` | Create a folder to group the assets or videos of a project |

#### Script

| Tool | Description |
| - | - |
| `generate_script` | Generate a video narration script from a prompt |

#### Video generation

| Tool | Description |
| - | - |
| `start_generation` | Start an AI video generation job |
| `get_generation_status` | Check the status and progress of a generation job |

#### Export

| Tool | Description |
| - | - |
| `start_export` | Start exporting a generated video to MP4 |
| `get_export_status` | Check the status of an export job |

#### Video management

| Tool | Description |
| - | - |
| `duplicate_video` | Duplicate a completed video, optionally changing the voice or avatar |

#### Assets

| Tool | Description |
| - | - |
| `list_asset_models` | List available image/video generation models |
| `get_asset_model` | Get a model's capabilities and input schema |
| `get_asset_pricing` | Compute the credit cost of a generation before starting it |
| `start_asset` | Start an image or video asset generation |
| `get_asset_status` | Check the status of an asset generation |

## Typical workflow

```text theme={null}
1. get_space_info                     →  check remaining credits
2. list_voices / list_avatars        →  pick a voice & avatar
3. generate_script (optional)        →  get narration text
4. start_generation                  →  get job_id
5. get_generation_status (polling)   →  get video_id
6. start_export                      →  get export job_id
7. get_export_status (polling)       →  get MP4 download URL
```

## Working in folders

The assistant is instructed to keep a project's assets together instead of dropping them loose in your media library. When you start something that will produce more than one asset — a video, a campaign, a batch of variations — it looks for a matching folder and, if there is none, proposes creating one before generating:

```text theme={null}
1. list_folders({ type: "assets" })   →  is there already a folder for this project?
2. create_folder (if none fits)      →  get folder_id, named after the project
3. start_asset ({ folder_id, ... })  →  every asset of the project lands in that folder
4. get_asset_status (polling)        →  get the result URLs
```

The same folder is reused for the rest of the project, and sub-folders can be nested with `parent_folder_id` (e.g. *Product shots* inside *Spring campaign*). You can always tell the assistant which folder to use, or ask it to create one at any point.

<Note>
  Edits, animations and variations started with `parent_media_id` automatically inherit the source asset's folder — no `folder_id` needed.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Pro plan required&#x22; during sign-in">
    The MCP server can only connect workspaces on a **Pro** plan or higher. If none of your workspaces is eligible, upgrade at [app.hoox.video](https://app.hoox.video).
  </Accordion>

  <Accordion title="Connected to the wrong workspace">
    The workspace is chosen once, on the authorization screen. Disconnect the Hoox connector in your client, reconnect, and pick another workspace.
  </Accordion>

  <Accordion title="Error insufficient_credits (402)">
    Your workspace has run out of credits. Top up from the Hoox dashboard under **Settings → Billing**.
  </Accordion>

  <Accordion title="Tool not showing up in the client">
    Check the connector status in your client's settings and re-run the sign-in flow if needed. After updating the configuration, restart the client.
  </Accordion>

  <Accordion title="Generation stuck in &#x22;processing&#x22;">
    Video generation can take 1–5 minutes depending on duration and options. Use `get_generation_status` to monitor progress. If the job is stuck for more than 10 minutes, check the `error` field in the status response.
  </Accordion>
</AccordionGroup>


# Agent Skills
Source: https://docs.hoox.video/agent-tooling/skills

Install the Hoox agent skill into Cursor, Claude Code, or Windsurf

Agent skills give AI coding assistants (Cursor, Claude Code, Windsurf, etc.) deep knowledge of the Hoox API through a reusable, installable guide.

### Install

```bash theme={null}
npx skills add hoox-video/skill
```

Or install for a specific agent:

<CodeGroup>
  ```bash Cursor theme={null}
  npx skills add hoox-video/skill -a cursor
  ```

  ```bash Claude Code theme={null}
  npx skills add hoox-video/skill -a claude-code
  ```
</CodeGroup>

<Info>
  The skill collection is hosted on GitHub at [hoox-video/skill](https://github.com/hoox-video/skill).
</Info>

### Example prompts

<AccordionGroup>
  <Accordion title="Generate a video from a prompt">
    ```text theme={null}
    Use the Hoox API to generate a 60-second vertical product demo video for our new DTC skincare serum.
    Voice: use an English female conversational voice that feels like a creator.
    Avatar: use an avatar that looks like a lifestyle content creator.
    Highlight 3 key benefits, include one short testimonial quote, and end with a clear "Shop now" call-to-action.
    Export the final video to MP4 and return the download URL.
    ```
  </Accordion>

  <Accordion title="Generate a script">
    ```text theme={null}
    Use the Hoox API to generate a 90-second video script announcing our new loyalty program for our Shopify store.
    Duration: 90 seconds.
    Focus on benefits for repeat customers, how to earn points, and a limited-time launch bonus.
    Return the script text and estimated cost.
    ```
  </Accordion>

  <Accordion title="List voices and avatars">
    ```text theme={null}
    Use the Hoox API to list available voices filtered by language "en" and gender "female".
    Also list avatars filtered by place, action, emotion, and accessories.
    Return the results in a table with ID, name, and metadata so I can pick a brand ambassador style combo.
    ```
  </Accordion>

  <Accordion title="Export a video">
    ```text theme={null}
    Use the Hoox API to export video VIDEO_ID to MP4 in vertical format.
    Poll the export status until complete and return the download URL.
    ```
  </Accordion>

  <Accordion title="Generate a batch of assets into a dedicated folder">
    ```text theme={null}
    Use the Hoox API to generate 4 product hero images for our "Summer Drop" campaign.
    Create a dedicated asset folder for the campaign first, then generate every image into it.
    Then animate the best one into a short video — keep it linked to the source image in the
    dashboard history. Return the asset IDs grouped by folder.
    ```
  </Accordion>

  <Accordion title="Create a custom avatar">
    ```text theme={null}
    Use the Hoox API to create a custom avatar.
    Prompt: "A young lifestyle creator filming TikTok videos in a cozy living room, talking about home decor products"
    Style: iphone, format: vertical.
    Set up a webhook at https://my-server.com/webhook to receive the result.
    ```
  </Accordion>

  <Accordion title="Duplicate a video with a different voice">
    ```text theme={null}
    Use the Hoox API to duplicate video VIDEO_ID with a new voice.
    Pick a male English voice with a British accent.
    Then export the duplicated video to MP4.
    ```
  </Accordion>

  <Accordion title="Full workflow with webhook">
    ```text theme={null}
    Use the Hoox API to:
    1. Generate a 60-second script announcing our Black Friday sale for our online fashion store
    2. Start video generation with the script, a friendly female voice, and an avatar that looks like a fashion creator
    3. Use webhook URL https://my-server.com/hook for both generation and export
    4. Start the export once generation completes
    Return all job IDs so I can track them.
    ```
  </Accordion>
</AccordionGroup>

### What the skill covers

When you install the skill, your coding assistant gains access to a detailed guide covering:

* **Authentication** — How to configure the API key and rate limits
* **Video creation workflow** — The complete pipeline from script to MP4
* **All API endpoints** — Request/response formats for every endpoint
* **Asset organization & lineage** — Grouping batches in dedicated folders and preserving edit history with `parent_media_id`
* **Polling strategies** — Recommended intervals for generation and export status checks
* **Webhooks** — How to receive async notifications instead of polling
* **Error handling** — Error codes and recovery strategies
* **Credit system** — Cost estimation and tracking


# Seedream 4.5
Source: https://docs.hoox.video/api-reference/assets/image/bytedance/seedream-4.5

ByteDance · `seedream-4.5` · image

## Identifier

Use the model identifier `seedream-4.5` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–4 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `16:9`) |
| Resolutions | `1080p`, `2K`, `4K` (default `2K`) |

## Inputs

Pass reference media in the `references` array (0–4 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~0.4 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "seedream-4.5",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Seedream 5 Flash
Source: https://docs.hoox.video/api-reference/assets/image/bytedance/seedream-5-flash

ByteDance · `seedream-5-flash` · image

## Identifier

Use the model identifier `seedream-5-flash` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `16:9`) |
| Resolutions | `1K`, `2K` (default `2K`) |
| Max prompt length | 5000 chars |
| Tags | `new` |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~0.27 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "seedream-5-flash",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Seedream 5 Lite
Source: https://docs.hoox.video/api-reference/assets/image/bytedance/seedream-5-lite

ByteDance · `seedream-5-lite` · image

## Identifier

Use the model identifier `seedream-5-lite` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `16:9`) |
| Resolutions | `1080p`, `2K`, `4K` (default `2K`) |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~0.35 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "seedream-5-lite",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Flux 2 Max
Source: https://docs.hoox.video/api-reference/assets/image/flux/flux-2-max

Flux · `flux-2-max` · image

## Identifier

Use the model identifier `flux-2-max` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–4 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `9:16`) |
| Resolutions | `1080p`, `2K`, `4K` (default `2K`) |

## Inputs

Pass reference media in the `references` array (0–4 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~1 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "flux-2-max",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Flux 2 Pro
Source: https://docs.hoox.video/api-reference/assets/image/flux/flux-2-pro

Flux · `flux-2-pro` · image

## Identifier

Use the model identifier `flux-2-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–4 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `9:16`) |
| Resolutions | `1080p`, `2K`, `4K` (default `2K`) |

## Inputs

Pass reference media in the `references` array (0–4 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~0.45 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "flux-2-pro",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Flux 3
Source: https://docs.hoox.video/api-reference/assets/image/flux/flux-3-image

Flux · `flux-3-image` · image

## Identifier

Use the model identifier `flux-3-image` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `9:16`) |
| Resolutions | `1K`, `2K`, `4K` (default `2K`) |
| Tags | `new` |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~2.4 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "flux-3-image",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Nano Banana 2
Source: https://docs.hoox.video/api-reference/assets/image/gemini/nano-banana-2

Google Gemini · `nano-banana-2` · image

## Identifier

Use the model identifier `nano-banana-2` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–4 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `16:9`) |
| Resolutions | `1K`, `2K`, `4K` (default `2K`) |

## Inputs

Pass reference media in the `references` array (0–4 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~1.2 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "nano-banana-2",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Nano Banana 2.1
Source: https://docs.hoox.video/api-reference/assets/image/gemini/nano-banana-2.1

Google Gemini · `nano-banana-2.1` · image

## Identifier

Use the model identifier `nano-banana-2.1` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `16:9`) |
| Resolutions | `1K`, `2K`, `4K` (default `2K`) |
| Tags | `new` |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~0.6 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "nano-banana-2.1",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Nano Banana Lite
Source: https://docs.hoox.video/api-reference/assets/image/gemini/nano-banana-lite

Google Gemini · `nano-banana-lite` · image

## Identifier

Use the model identifier `nano-banana-lite` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–4 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `16:9`) |

## Inputs

Pass reference media in the `references` array (0–4 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters: **\~0.5 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "nano-banana-lite",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Nano Banana Pro
Source: https://docs.hoox.video/api-reference/assets/image/gemini/nano-banana-pro

Google Gemini · `nano-banana-pro` · image

## Identifier

Use the model identifier `nano-banana-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–4 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `16:9`) |
| Resolutions | `1K`, `2K`, `4K` (default `2K`) |

## Inputs

Pass reference media in the `references` array (0–4 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (`2K`): **\~1.5 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "nano-banana-pro",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Ideogram 4.5
Source: https://docs.hoox.video/api-reference/assets/image/ideogram/ideogram-4.5

Ideogram · `ideogram-4.5` · image

## Identifier

Use the model identifier `ideogram-4.5` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–5 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `9:16`) |
| Resolutions | `1K`, `2K` (default `2K`) |
| Max prompt length | 10000 chars |
| Tags | `new` |

## Inputs

Pass reference media in the `references` array (0–5 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `quality` | select | `medium` | yes | Rendering effort. Higher quality means more detail and a higher price. Options: `low`, `medium`, `high`. |
| `editPrecision` | select | `regular` | no | Only used when editing an image. high is a precise edit that restores every pixel the prompt does not touch, and keeps the source image's size: aspect ratio and resolution are then ignored. Options: `regular`, `high`. |

## Pricing

Default parameters (`2K`): **\~0.6 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "ideogram-4.5",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "2K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Muse Image
Source: https://docs.hoox.video/api-reference/assets/image/meta/muse-image

Meta · `muse-image` · image

## Identifier

Use the model identifier `muse-image` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `16:9`) |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters: **\~0.1 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "muse-image",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# GPT Image 2
Source: https://docs.hoox.video/api-reference/assets/image/openai/gpt-image-2

OpenAI · `gpt-image-2` · image

## Identifier

Use the model identifier `gpt-image-2` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `9:16`) |
| Resolutions | `1K`, `2K`, `4K` (default `1K`) |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `quality` | select | `medium` | yes | Rendering effort. Higher quality means more detail and a higher price. Options: `low`, `medium`, `high`. |

## Pricing

Default parameters (`1K`): **\~0.3 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "gpt-image-2",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "1K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# GPT Image 2.5 Flare
Source: https://docs.hoox.video/api-reference/assets/image/openai/gpt-image-2.5-flare

OpenAI · `gpt-image-2.5-flare` · image

## Identifier

Use the model identifier `gpt-image-2.5-flare` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `9:16`) |
| Resolutions | `1K`, `2K`, `4K` (default `1K`) |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `quality` | select | `high` | yes | Rendering effort. Higher quality means more detail and a higher price. Options: `low`, `medium`, `high`, `xhigh`, `max`. |

## Pricing

Default parameters (`1K`): **\~0.3 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "gpt-image-2.5-flare",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "1K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# GPT Image 2.5 Sunburst
Source: https://docs.hoox.video/api-reference/assets/image/openai/gpt-image-2.5-sunburst

OpenAI · `gpt-image-2.5-sunburst` · image

## Identifier

Use the model identifier `gpt-image-2.5-sunburst` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `9:16`) |
| Resolutions | `1K`, `2K`, `4K` (default `1K`) |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `quality` | select | `high` | yes | Rendering effort. Higher quality means more detail and a higher price. Options: `low`, `medium`, `high`, `xhigh`, `max`. |

## Pricing

Default parameters (`1K`): **\~0.3 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "1K"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Grok Image
Source: https://docs.hoox.video/api-reference/assets/image/xai/grok-imagine-image

xAI Grok · `grok-imagine-image` · image

## Identifier

Use the model identifier `grok-imagine-image` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–1 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `3:2`, `2:3`, `4:3`, `3:4` (default `16:9`) |

## Inputs

Pass reference media in the `references` array (0–1 item). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters: **\~0.25 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "grok-imagine-image",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Z-Image Turbo
Source: https://docs.hoox.video/api-reference/assets/image/zimage/z-image-turbo

Z-Image · `z-image-turbo` · image

## Identifier

Use the model identifier `z-image-turbo` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–1 |
| Aspect ratios | `16:9`, `9:16`, `1:1`, `4:3`, `3:4` (default `16:9`) |

## Inputs

Pass reference media in the `references` array (0–1 item). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters: **\~0.1 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "image",
  "model": "z-image-turbo",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Get Asset Model
Source: https://docs.hoox.video/api-reference/assets/model

GET https://app.hoox.video/api/public/v1/asset/models/{name}
Retrieve full details for a single asset generation model, including a JSON-schema-shaped input description

## Overview

Returns the complete configuration of a model: capabilities, custom settings, restrictions, and a JSON-schema-shaped `input_schema` describing exactly what the model accepts.

The `input_schema` is suitable for use as an AI tool / function definition (e.g. AI SDK, MCP server, OpenAI tools).

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Path Parameters

<ParamField type="string">
  Model identifier (e.g. `veo-3.1-lite`, `seedance-2.0`, `nano-banana-pro`). Use [List Models](/api-reference/assets/models) to discover available identifiers.
</ParamField>

## Response

All fields from the [model summary](/api-reference/assets/models) plus:

<ResponseField name="settings" type="array">
  Custom settings accepted in the `model_settings` object of the submit request.

  <Expandable title="setting">
    <ResponseField name="key" type="string" />

    <ResponseField name="type" type="string">`boolean` or `select`.</ResponseField>

    <ResponseField name="label" type="string" />

    <ResponseField name="default_value" />

    <ResponseField name="affects_cost" type="boolean" />

    <ResponseField name="options" type="array">
      Present for `select` type. Each option has `value` and `label`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="max_prompt_length" type="number">
  Maximum number of characters accepted in the `prompt` field.
</ResponseField>

<ResponseField name="restricted_countries" type="array">
  ISO country codes where this model is not available.
</ResponseField>

<ResponseField name="input_schema" type="object">
  JSON-schema-shaped object listing the accepted request fields, their types, and enums. Only the fields the model actually accepts are listed. `duration` is always expressed in **seconds** (integer).

  <Expandable title="properties">
    <ResponseField name="type" type="string">Always `object`.</ResponseField>

    <ResponseField name="properties" type="object">
      Map of field name → JSON Schema property (with `type`, `enum`, `default`, `minItems`, etc.).
    </ResponseField>

    <ResponseField name="required" type="array" />
  </Expandable>
</ResponseField>

<Note>
  **Reference media in `input_schema`.** For most models, reference inputs appear under a single `references` array. Models that need specific typed inputs (e.g. first/last frame, motion control, video edit) instead expose **named top-level fields** — such as `first_frame`, `last_frame`, `start_image`, `motion_video`, or `source_video`. Either way, every reference object accepts exactly one of `url`, `asset_id`, or `avatar_id`. See each model's page for its named slots.
</Note>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/asset/models/veo-3.1-lite" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.hoox.video/api/public/v1/asset/models/veo-3.1-lite",
      headers={"Authorization": "Bearer your_api_key"},
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/asset/models/veo-3.1-lite', {
    headers: { 'Authorization': 'Bearer your_api_key' },
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "name": "veo-3.1-lite",
    "label": "Veo 3.1 Lite",
    "type": "video",
    "provider": "google",
    "base_cost": 4,
    "has_audio": true,
    "capabilities": {
      "max_images": 1,
      "min_images": 0
    },
    "settings": [
      {
        "key": "generateAudio",
        "type": "boolean",
        "label": "audio",
        "default_value": true,
        "affects_cost": true
      }
    ],
    "input_schema": {
      "type": "object",
      "required": ["prompt"],
      "properties": {
        "prompt": { "type": "string", "description": "Text prompt describing the asset to generate." },
        "references": {
          "type": "array",
          "description": "Reference media. Min 0, max 1.",
          "items": {
            "type": "object",
            "description": "Exactly one of url, asset_id, or avatar_id must be set.",
            "properties": {
              "url": { "type": "string", "format": "uri", "description": "Direct publicly accessible URL of the media file." },
              "asset_id": { "type": "string", "description": "ID of an existing asset in your Hoox space media library." },
              "avatar_id": { "type": "string", "description": "ID of an avatar defined in your Hoox space." }
            },
            "oneOf": [{ "required": ["url"] }, { "required": ["asset_id"] }, { "required": ["avatar_id"] }]
          },
          "minItems": 0,
          "maxItems": 1
        },
        "aspect_ratio": { "type": "string", "enum": ["16:9", "9:16"], "default": "9:16" },
        "resolution":   { "type": "string", "enum": ["720p", "1080p"], "default": "720p" },
        "duration":     { "type": "integer", "description": "Duration in seconds.", "enum": [4, 6, 8], "default": 8 },
        "generation_count": { "type": "integer", "minimum": 1, "maximum": 4, "default": 1 },
        "model_settings": {
          "type": "object",
          "properties": { "generateAudio": { "type": "boolean", "default": true } }
        }
      }
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Model \"not-a-real-model\" not found",
    "details": [
      { "code": "model_not_found", "message": "Model \"not-a-real-model\" not found" }
    ]
  }
  ```
</ResponseExample>


# List Asset Models
Source: https://docs.hoox.video/api-reference/assets/models

GET https://app.hoox.video/api/public/v1/asset/models
List all available asset generation models with their capabilities, optionally filtered

## Overview

Returns a summary of every model available for asset generation. Each model includes its provider, type, capabilities (aspect ratios, resolutions, durations, etc.), tags, and base cost.

Use this to discover which models exist and what they can do. For the full JSON schema of an individual model (including input schema and settings), use [Get Model](/api-reference/assets/model).

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Query Parameters

<ParamField type="string">
  Filter by media type: `image` or `video`.
</ParamField>

<ParamField type="string">
  Filter by provider (e.g. `google`, `kling`, `bytedance`, `flux`, `ideogram`, `xai`).
</ParamField>

<ParamField type="string">
  Filter by tag (e.g. `motion-control`, `video-edit`, `extend`, `new`).
</ParamField>

## Response

<ResponseField name="models" type="array">
  Array of model summary objects.

  <Expandable title="model summary">
    <ResponseField name="name" type="string">
      Model identifier — use this in the `model` field of [`/asset/start`](/api-reference/assets/start).
    </ResponseField>

    <ResponseField name="label" type="string">
      Human-readable model name.
    </ResponseField>

    <ResponseField name="type" type="string">
      `image` or `video`.
    </ResponseField>

    <ResponseField name="provider" type="string">
      Omitted from each item when filtering by `provider` (hoisted to the root — see note below).
    </ResponseField>

    <ResponseField name="tags" type="array">
      Omitted entirely when the model has no tags.
    </ResponseField>

    <ResponseField name="base_cost" type="number">
      Base credit cost (for the model's default configuration).
    </ResponseField>

    <ResponseField name="has_audio" type="boolean" />

    <ResponseField name="required_plans" type="array">
      Plan names required to use this model (empty if available on all plans).
    </ResponseField>

    <ResponseField name="capabilities" type="object">
      Includes `max_images`, `min_images`, `supported_aspect_ratios`, `default_aspect_ratio`, `supported_resolutions`, `default_resolution`, `supported_durations`, `default_duration`, `input_types`, `resolution_constraints`. Durations are expressed in **seconds** (numbers).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number">
  Number of models in the response (after filtering).
</ResponseField>

<Note>
  **Hoisted filters.** When you filter by `type` and/or `provider`, that value is the same for every result, so it is returned **once at the root** of the response and omitted from each item (to save payload size). Unfiltered requests keep `type` and `provider` on each item.
</Note>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/asset/models?type=video&provider=kling" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/asset/models"
  params = {"type": "video", "provider": "kling"}
  headers = {"Authorization": "Bearer your_api_key"}
  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/asset/models');
  url.searchParams.set('type', 'video');
  url.searchParams.set('provider', 'kling');

  const response = await fetch(url, {
    headers: { 'Authorization': 'Bearer your_api_key' },
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "type": "video",
    "provider": "kling",
    "models": [
      {
        "name": "kling-pro",
        "label": "Kling 2.6 Pro",
        "base_cost": 7.5,
        "has_audio": true,
        "capabilities": {
          "max_images": 1,
          "min_images": 0,
          "supported_aspect_ratios": ["16:9", "9:16", "1:1"],
          "default_aspect_ratio": "9:16",
          "supported_durations": [5, 10],
          "default_duration": 5
        }
      }
    ],
    "count": 1
  }
  ```

  ```json 400 Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      { "code": "invalid_value", "message": "type must be 'image' or 'video'", "field": "type" }
    ]
  }
  ```
</ResponseExample>


# Get Asset Pricing
Source: https://docs.hoox.video/api-reference/assets/pricing

POST https://app.hoox.video/api/public/v1/asset/pricing
Dry-run cost calculation for a model with given parameters — does not debit credits

## Overview

Returns the exact credit cost for a generation with the given parameters, without submitting a job and without debiting credits. Useful to display a price preview before letting the user submit.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField type="string">
  Model identifier (e.g. `veo-3.1-lite`).
</ParamField>

<ParamField type="integer">
  Duration **in seconds** (e.g. `8`). Used by video models. See the model's supported durations via [Get Model](/api-reference/assets/model). For [`hoox-upscale`](/api-reference/assets/video/hoox/hoox-upscale), pass the duration of the source video.
</ParamField>

<ParamField type="string">
  Resolution (e.g. `720p`, `1080p`, `2K`).
</ParamField>

<ParamField type="object">
  Custom model settings such as `generateAudio`. Some settings affect cost — see the model page.
</ParamField>

<ParamField type="number">
  Number of reference images. Used by models whose price depends on the references (e.g. `minimax-h3-max`).
</ParamField>

<ParamField type="number">
  Number of variations. Multiplies `cost_per_generation`.
</ParamField>

## Response

<ResponseField name="model" type="string" />

<ResponseField name="cost_per_generation" type="number">
  Credits for one generation.
</ResponseField>

<ResponseField name="total_cost" type="number">
  `cost_per_generation × generation_count`.
</ResponseField>

<ResponseField name="currency" type="string">
  Always `credits`.
</ResponseField>

<ResponseField name="generation_count" type="number" />

<ResponseField name="normalized" type="object">
  Present **only when the engine coerced one of your inputs** to a different supported value
  (e.g. an unsupported duration snapped to the nearest valid one). Each field appears only if it
  differs from what you sent. Omitted entirely when nothing was changed.

  <Expandable title="properties">
    <ResponseField name="duration" type="number">
      Resolved duration in seconds.
    </ResponseField>

    <ResponseField name="resolution" type="string" />
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/pricing" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "veo-3.1-lite",
      "duration": 8,
      "resolution": "1080p",
      "generation_count": 2
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://app.hoox.video/api/public/v1/asset/pricing",
      headers={"Authorization": "Bearer your_api_key"},
      json={
          "model": "veo-3.1-lite",
          "duration": 8,
          "resolution": "1080p",
          "generation_count": 2,
      },
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/asset/pricing', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'veo-3.1-lite',
      duration: 8,
      resolution: '1080p',
      generation_count: 2,
    }),
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "model": "veo-3.1-lite",
    "cost_per_generation": 6.4,
    "total_cost": 12.8,
    "currency": "credits",
    "generation_count": 2
  }
  ```

  ```json 200 OK (input coerced) theme={null}
  {
    "model": "veo-3.1-lite",
    "cost_per_generation": 6.4,
    "total_cost": 12.8,
    "currency": "credits",
    "generation_count": 2,
    "normalized": {
      "duration": 8
    }
  }
  ```

  ```json 400 Missing Model theme={null}
  {
    "error": "Validation failed",
    "details": [
      { "code": "missing_field", "message": "model is required", "field": "model" }
    ]
  }
  ```

  ```json 404 Unknown Model theme={null}
  {
    "error": "Model \"not-a-real-model\" not found",
    "details": [
      { "code": "model_not_found", "message": "Model \"not-a-real-model\" not found" }
    ]
  }
  ```
</ResponseExample>


# Submit Asset Generation
Source: https://docs.hoox.video/api-reference/assets/start

POST https://app.hoox.video/api/public/v1/asset/start
Start generating one or more images or videos with any supported model

## Overview

Submits an asset (image or video) generation job and returns immediately with the IDs of the temporary assets being generated. Generations run in the background — poll [`/asset/status/{assetId}`](/api-reference/assets/status) to track progress.

Credits are debited up front based on the model and the parameters you send. Failed generations are automatically refunded.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField type="string">
  `image` or `video`. Must match the type of the model you select.
</ParamField>

<ParamField type="string">
  The model identifier. See [List Models](/api-reference/assets/models) for available identifiers and capabilities.
</ParamField>

<ParamField type="string">
  Text prompt describing the asset to generate. Some models cap the prompt length — check the model page. Promptless models such as [`hoox-upscale`](/api-reference/assets/video/hoox/hoox-upscale) do not take one.
</ParamField>

<ParamField type="array">
  Reference media for the model. Required for image-to-video, motion control, edit, and reference-based models.

  Models with named input slots (e.g. `kling-motion-control`, `kling-v3-pro`) expect **dedicated top-level fields** instead — see [Named input slots](#named-input-slots) below. They still accept a `references` array, mapped onto their slots in order, so you never have to migrate an existing call.

  Each item must have **exactly one** of:

  <Expandable title="item properties">
    <ParamField type="string">
      Direct publicly accessible URL of the reference media file. Supported formats:

      * Images: `.jpg` / `.jpeg` / `.png` / `.webp`
      * Videos: `.mp4` / `.mov` / `.webm` / `.m4v`
    </ParamField>

    <ParamField type="string">
      ID of an existing asset in your Hoox space media library (as returned by `/asset/start` or `/asset/status`).
      The server resolves the URL automatically — no need to re-upload.
    </ParamField>

    <ParamField type="string">
      ID of an avatar defined in your Hoox space. The avatar's thumbnail image is used as the reference.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  Named characters or objects to inject in the generation, each described by several images of the same subject and referenced in the prompt as `@name`. Only for models that expose an element capability (`kling-v3-pro`, `kling-v3-standard`) — see [Elements](#elements) below.

  <Expandable title="item properties">
    <ParamField type="string">
      Alias used in the prompt as `@name`. Letters, digits and underscores only, 32 characters max.
    </ParamField>

    <ParamField type="array">
      **At least 2** images of the same subject — frontal view first, then other angles. Each item takes exactly one of `url`, `asset_id`, or `avatar_id`, like a `references` item.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="number">
  Number of variations to generate from the same prompt. Must be between 1 and 4. Credits are debited per generation.
</ParamField>

<ParamField type="string">
  One of the model's supported aspect ratios. Defaults to the model's default if omitted.
</ParamField>

<ParamField type="string">
  One of the model's supported resolutions. Defaults to the model's default if omitted.
</ParamField>

<ParamField type="integer">
  Video duration **in seconds** (e.g. `8`). Use one of the model's supported durations — see the `duration` enum in the model's `input_schema` from [Get Model](/api-reference/assets/model). The server converts it to the model's expected format automatically.
</ParamField>

<ParamField type="object">
  Per-model toggles such as `generateAudio`, `camera_fixed`, `quality`. See the model page for available keys.
</ParamField>

<ParamField type="string">
  ID of the **source asset this generation is derived from** — an edit, animation (image-to-video), upscale, restyle, or variation. Set it whenever the output comes from an existing asset: it links the new asset to its source in the dashboard's **history tree** so the full edit chain stays visible.

  This is separate from the model input: keep passing the source as a reference (`asset_id` / named slot like `source_video`) so the model receives it, **and** set `parent_media_id` to the same source id to record the lineage.

  When set, the generated assets also inherit the parent's folder, and `folder_id` is ignored.
</ParamField>

<ParamField type="string">
  ID of an existing **asset folder** to place the generated asset(s) into. Create one with [Create Folder](/api-reference/folders/create) (`type: "assets"`) or list existing ones with [List Folders](/api-reference/folders/list). When working on a project or generating a batch, group its outputs in a dedicated folder so they stay organized and easy to find in the dashboard.
</ParamField>

<ParamField type="string">
  For Seedance 2.0 UGC only — appearance and actions of the subject (separate from the script).
</ParamField>

<ParamField type="string">
  URL that will receive a notification when generation completes (success or failure).
</ParamField>

<ParamField type="string">
  Predefined base file name for the produced asset, without extension (e.g. `summer-campaign-hero`). It is slugified server-side (lowercased, non-alphanumeric characters replaced by hyphens) and the correct extension is appended automatically. When omitted, a descriptive name is generated from the prompt.
</ParamField>

## Named input slots

Some models require specific media types in a fixed order — for example, a subject image **and** a motion reference video. For these models, instead of a generic `references[]` array, you pass named top-level properties that make the intent explicit.

The named properties for a given model are listed on its model page and in the `input_schema` field returned by [`GET /models/{name}`](/api-reference/assets/model).

Each named slot accepts the same object shape as a `references[]` item: exactly one of `url`, `asset_id`, or `avatar_id`. Slots are ordered — when a slot is optional, you may omit it, but you cannot provide a later slot while leaving an earlier one empty (e.g. `last_frame` requires `first_frame`).

**Models with named slots:**

| Model | Named slots |
| - | - |
| `kling-pro` | `start_image` (optional) + `end_image` (optional) |
| `kling-v3-pro`, `kling-v3-standard` | `first_frame` (optional) + `last_frame` (optional) |
| `kling-motion-control`, `kling-motion-control-pro`, `kling-v3-motion-pro`, `kling-v3-motion-standard` | `start_image` + `motion_video` |
| `kling-o3-edit-pro`, `kling-o3-edit-standard` | `source_video` |
| `flux-3-video-extend`, `flux-3-video-edit`, `grok-imagine-video-edit`, `bytedance-upscaler` | `source_video` |

<Note>
  Passing a `references` array to one of these models is still supported: the items are mapped onto the slots above in order (first item → first slot, and so on). Named fields are clearer and are what the model pages document, but existing calls keep working.
</Note>

## Elements

Elements let you inject **named characters or objects** in a generation. Each element is described by several images of the same subject, and you refer to it in the prompt with `@name` — so a single prompt can direct several known subjects without ambiguity.

Supported by `kling-v3-pro` and `kling-v3-standard`, up to **4 elements** per request.

```json theme={null}
{
  "type": "video",
  "model": "kling-v3-pro",
  "prompt": "@sarah picks up @mug and takes a slow sip, then smiles at the camera.",
  "first_frame": { "url": "https://example.com/kitchen.jpg" },
  "elements": [
    {
      "name": "sarah",
      "images": [
        { "url": "https://example.com/sarah-frontal.jpg" },
        { "url": "https://example.com/sarah-profile.jpg" }
      ]
    },
    {
      "name": "mug",
      "images": [
        { "asset_id": "662f8c1d3a4b5e6f70123456" },
        { "asset_id": "662f8c1d3a4b5e6f70123457" }
      ]
    }
  ],
  "duration": 5
}
```

**Rules**

* Each element needs **at least 2 images** of the same subject: the first is the frontal view, the others are additional angles (4 max).
* The prompt **must reference every element** as `@name`. An unreferenced element is ignored by the model, so the request is rejected instead of burning credits.
* `name` accepts letters, digits and underscores only (32 characters max), must be unique within the request, and cannot be `refN` or `elementN` — those are reserved for the internal rewriting of prompt references.
* `first_frame` is required whenever you send elements.
* Element images do **not** count toward the model's `references` / named-slot limits.

Element names are yours: Hoox rewrites them into the positional placeholders the provider expects before submitting, so `@sarah` and `@mug` are what you write and what you read back in your own code.

## Response

<ResponseField name="asset_ids" type="array">
  IDs of the created temporary assets. One ID per generation. Use these with [`/asset/status/{assetId}`](/api-reference/assets/status).
</ResponseField>

<ResponseField name="status" type="string">
  Always `generating` on success.
</ResponseField>

<ResponseField name="count" type="number">
  Number of generations launched.
</ResponseField>

<ResponseField name="cost_per_generation" type="number">
  Credits charged for one generation.
</ResponseField>

<ResponseField name="total_cost" type="number">
  Total credits debited (`cost_per_generation × count`).
</ResponseField>

## Examples

<RequestExample>
  ```bash Text-to-video (no references) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "veo-3.1-lite",
      "prompt": "A cinematic shot of a fox running through autumn leaves at sunrise.",
      "aspect_ratio": "9:16",
      "duration": 8,
      "resolution": "720p"
    }'
  ```

  ```bash Text-to-image into a folder theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "image",
      "model": "flux-2-pro",
      "prompt": "Product shot of a ceramic mug on a marble counter.",
      "aspect_ratio": "1:1",
      "folder_id": "662f8c1d3a4b5e6f70123456"
    }'
  ```

  ```bash Image-to-video (URL reference) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "grok-imagine-video",
      "prompt": "The subject walks forward confidently.",
      "references": [
        { "url": "https://example.com/subject.jpg" }
      ],
      "duration": 6,
      "resolution": "720p"
    }'
  ```

  ```bash Image-to-video (existing Hoox asset) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "grok-imagine-video",
      "prompt": "The subject walks forward confidently.",
      "references": [
        { "asset_id": "662f8c1d3a4b5e6f70123456" }
      ],
      "duration": 6
    }'
  ```

  ```bash Animate an existing asset (keeps history) theme={null}
  # Derive a video from an existing image asset. The asset is passed BOTH as the
  # model reference AND as parent_media_id, so the dashboard links them in the
  # history tree (and the video inherits the image's folder).
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "grok-imagine-video",
      "prompt": "The subject turns slowly toward the camera.",
      "references": [
        { "asset_id": "662f8c1d3a4b5e6f70123456" }
      ],
      "parent_media_id": "662f8c1d3a4b5e6f70123456"
    }'
  ```

  ```bash Image-to-video (Hoox avatar) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "kling-v3-pro",
      "prompt": "The character smiles and waves at the camera.",
      "references": [
        { "avatar_id": "6630000000000000deadbeef" }
      ]
    }'
  ```

  ```bash Motion control (named slots) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "kling-v3-motion-pro",
      "prompt": "Apply the motion to the subject naturally.",
      "start_image": { "url": "https://example.com/subject.jpg" },
      "motion_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
    }'
  ```

  ```bash Flux 3 keyframes (3+ references) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "flux-3-video",
      "prompt": "One continuous shot moving through the three scenes.",
      "references": [
        { "url": "https://example.com/keyframe-1.jpg" },
        { "url": "https://example.com/keyframe-2.jpg" },
        { "url": "https://example.com/keyframe-3.jpg" }
      ],
      "aspect_ratio": "16:9",
      "duration": 10
    }'
  ```

  ```bash Kling 3 first / last frame theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "kling-v3-pro",
      "prompt": "The camera pushes in slowly as the scene transforms.",
      "first_frame": { "url": "https://example.com/frame-start.jpg" },
      "last_frame": { "url": "https://example.com/frame-end.jpg" },
      "aspect_ratio": "9:16",
      "duration": 5
    }'
  ```

  ```bash Kling 3 elements (@mentions) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "kling-v3-pro",
      "prompt": "@sarah walks into the kitchen and picks up @mug, then smiles at the camera.",
      "first_frame": { "url": "https://example.com/kitchen.jpg" },
      "elements": [
        {
          "name": "sarah",
          "images": [
            { "url": "https://example.com/sarah-frontal.jpg" },
            { "url": "https://example.com/sarah-profile.jpg" }
          ]
        },
        {
          "name": "mug",
          "images": [
            { "asset_id": "662f8c1d3a4b5e6f70123456" },
            { "asset_id": "662f8c1d3a4b5e6f70123457" }
          ]
        }
      ],
      "duration": 5
    }'
  ```

  ```bash Video edit (named slot) theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/asset/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "video",
      "model": "kling-o3-edit-pro",
      "prompt": "Change the background to a tropical beach.",
      "source_video": { "asset_id": "662f8c1d3a4b5e6f70123456" }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "asset_ids": ["662f8c1d3a4b5e6f70123456"],
    "status": "generating",
    "count": 1,
    "cost_per_generation": 60,
    "total_cost": 60
  }
  ```

  ```json 400 Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      { "code": "missing_field", "message": "prompt is required", "field": "prompt" }
    ]
  }
  ```

  ```json 400 Invalid Elements theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "invalid_value",
        "message": "elements[0].images requires at least 2 images of the same subject (frontal view first, then other angles). Provided: 1",
        "field": "elements[0].images"
      },
      {
        "code": "invalid_value",
        "message": "The prompt must reference elements[1] as @mug",
        "field": "elements[1].name"
      }
    ]
  }
  ```

  ```json 402 Insufficient Credits theme={null}
  {
    "error": "Insufficient credits. Required: 60, Available: 12",
    "details": [
      { "code": "not_eligible", "message": "Insufficient credits. Required: 60, Available: 12" }
    ]
  }
  ```

  ```json 403 Plan Required theme={null}
  {
    "error": "This model requires one of the following plans: PRO, ENTREPRISE.",
    "details": [
      { "code": "not_eligible", "message": "This model requires one of the following plans: PRO, ENTREPRISE." }
    ]
  }
  ```
</ResponseExample>

## Notes

* The endpoint returns as soon as the temp assets are created — the actual generation runs in the background and typically completes in 10–120 seconds depending on the model.
* If you provide a `webhook_url`, it will be called when generation completes (success or failure).
* Use [List Models](/api-reference/assets/models) and [Get Model](/api-reference/assets/model) to discover the parameters each model accepts, including named input slots and element support.
* Use [Get Pricing](/api-reference/assets/pricing) for a dry-run cost estimate before submitting.
* When a generation is derived from an existing asset (edit, animation, upscale, restyle, variation), set `parent_media_id` to the source asset's id so the dashboard keeps the full history chain. Pass the source as a reference for the model **and** as `parent_media_id` for the lineage.


# Check Asset Status
Source: https://docs.hoox.video/api-reference/assets/status

GET https://app.hoox.video/api/public/v1/asset/status/{assetId}
Retrieve the current generation status and result of a previously submitted asset

## Overview

Returns the current state of an asset (generating, completed, or failed) along with its result URL and metadata once ready. Poll this endpoint to wait for a generation to complete.

This endpoint reads the asset state from the database only — it does not poll the underlying provider (FAL/Kie). The asset state is kept up to date by webhooks.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Path Parameters

<ParamField type="string">
  Asset ID returned by [`/asset/start`](/api-reference/assets/start) in the `asset_ids` array.
</ParamField>

## Response

<ResponseField name="asset_id" type="string">
  The asset ID that was queried.
</ResponseField>

<ResponseField name="status" type="string">
  One of `generating`, `completed`, `failed`, or `pending`.
</ResponseField>

<ResponseField name="type" type="string">
  Media type: `image`, `video`, or `audio`.
</ResponseField>

<ResponseField name="url" type="string">
  URL of the generated media. Present when `status` is `completed`.
</ResponseField>

<ResponseField name="thumbnail_url" type="string">
  Preview thumbnail URL (first frame of the video). **Videos only** — omitted for images, where it would just repeat `url`.
</ResponseField>

<ResponseField name="width" type="number">
  Width in pixels of the generated media (when known).
</ResponseField>

<ResponseField name="height" type="number">
  Height in pixels of the generated media (when known).
</ResponseField>

<ResponseField name="duration_seconds" type="number">
  Duration in seconds (videos only).
</ResponseField>

<ResponseField name="cost" type="number">
  Credits debited for this generation.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="generation_params" type="object">
  The parameters used to generate the asset.

  <Expandable title="properties">
    <ResponseField name="model" type="string">
      Model identifier (e.g. `gemini-omni-video`).
    </ResponseField>

    <ResponseField name="prompt" type="string">
      Original prompt sent.
    </ResponseField>

    <ResponseField name="aspect_ratio" type="string" />

    <ResponseField name="resolution" type="string" />

    <ResponseField name="duration" type="number">
      Duration in seconds.
    </ResponseField>

    <ResponseField name="references" type="array">
      Reference media used as input for this generation, in the order they were submitted (for models with [named input slots](/api-reference/assets/start#named-input-slots), slot order). Omitted when the generation used no reference.

      Each item has **exactly one** of the fields below — the same shape accepted by [`/asset/start`](/api-reference/assets/start), so a reference can be fed straight back into a new generation.

      <Expandable title="item properties">
        <ResponseField name="asset_id" type="string">
          The reference came from an asset in your space media library. Only the ID is returned — call [`/asset/status/{assetId}`](/api-reference/assets/status) on it to get its URL.
        </ResponseField>

        <ResponseField name="avatar_id" type="string">
          The reference came from an avatar defined in your space (its thumbnail was used).
        </ResponseField>

        <ResponseField name="url" type="string">
          Direct URL of the reference media, for references submitted as a `url`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Present when `status` is `failed`.

  <Expandable title="properties">
    <ResponseField name="code" type="string" />

    <ResponseField name="message" type="string" />
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/asset/status/662f8c1d3a4b5e6f70123456" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  asset_id = "662f8c1d3a4b5e6f70123456"
  url = f"https://app.hoox.video/api/public/v1/asset/status/{asset_id}"
  headers = {"Authorization": "Bearer your_api_key"}
  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const assetId = '662f8c1d3a4b5e6f70123456';
  const response = await fetch(`https://app.hoox.video/api/public/v1/asset/status/${assetId}`, {
    headers: { 'Authorization': 'Bearer your_api_key' },
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK · generating theme={null}
  {
    "asset_id": "662f8c1d3a4b5e6f70123456",
    "status": "generating",
    "type": "video",
    "generation_params": {
      "model": "gemini-omni-video",
      "prompt": "A cinematic shot of a fox running through autumn leaves at sunrise.",
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 8,
      "references": [
        { "asset_id": "662f8c1d3a4b5e6f70123401" },
        { "url": "https://example.com/reference.jpg" }
      ]
    }
  }
  ```

  ```json 200 OK · completed theme={null}
  {
    "asset_id": "662f8c1d3a4b5e6f70123456",
    "status": "completed",
    "type": "video",
    "url": "https://cdn.hoox.video/spaces/.../video.mp4",
    "thumbnail_url": "https://cdn.hoox.video/spaces/.../thumb.jpg",
    "width": 720,
    "height": 1280,
    "duration_seconds": 8,
    "cost": 8,
    "created_at": "2026-05-22T14:30:00.000Z",
    "generation_params": {
      "model": "gemini-omni-video",
      "prompt": "A cinematic shot of a fox running through autumn leaves at sunrise.",
      "aspect_ratio": "9:16",
      "resolution": "720p",
      "duration": 8,
      "references": [
        { "asset_id": "662f8c1d3a4b5e6f70123401" },
        { "url": "https://example.com/reference.jpg" }
      ]
    }
  }
  ```

  ```json 200 OK · failed theme={null}
  {
    "asset_id": "662f8c1d3a4b5e6f70123456",
    "status": "failed",
    "type": "video",
    "error": {
      "code": "GENERATION_ERROR",
      "message": "The prompt was rejected by the content filter."
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "Asset 662f8c1d3a4b5e6f70123456 not found in space 5e6f7012345...",
    "details": [
      { "code": "asset_not_found", "message": "Asset 662f8c1d3a4b5e6f70123456 not found in space 5e6f7012345..." }
    ]
  }
  ```
</ResponseExample>

## Polling guidance

A typical pattern is to poll every 2–5 seconds until `status` is `completed` or `failed`. Most generations complete in under 2 minutes. If you provided a `webhook_url` when submitting, you can avoid polling entirely.


# Wan 3.0
Source: https://docs.hoox.video/api-reference/assets/video/alibaba/wan-3.0

Alibaba Wan · `wan-3.0` · video

## Identifier

Use the model identifier `wan-3.0` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–20 |
| Aspect ratios | `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `9:16`) |
| Resolutions | `480p`, `720p`, `1080p` (default `1080p`) |
| Durations (seconds) | `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30` (default `5`) |
| Audio | yes |
| Max prompt length | 20000 chars |

## Inputs

Pass reference media in the `references` array (0–20 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |
| `forceReferenceMode` | boolean | `false` | no | Use the attached media as subject/style references instead of the video's first frame. Reference mode turns on by itself from 3 references, or as soon as a video or an audio is attached; set this to get it with fewer — one reference is enough. |

## Pricing

Default parameters (5s at `1080p`): **\~10 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "wan-3.0",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Wan 3.0 Prime
Source: https://docs.hoox.video/api-reference/assets/video/alibaba/wan-3.0-prime

Alibaba Wan · `wan-3.0-prime` · video

## Identifier

Use the model identifier `wan-3.0-prime` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–20 |
| Aspect ratios | `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `9:16`) |
| Resolutions | `480p`, `720p`, `1080p` (default `1080p`) |
| Durations (seconds) | `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30` (default `5`) |
| Audio | yes |
| Max prompt length | 20000 chars |

## Inputs

Pass reference media in the `references` array (0–20 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |
| `forceReferenceMode` | boolean | `false` | no | Use the attached media as subject/style references instead of the video's first frame. Reference mode turns on by itself from 3 references, or as soon as a video or an audio is attached; set this to get it with fewer — one reference is enough. |

## Pricing

Default parameters (5s at `1080p`): **\~14 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "wan-3.0-prime",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Seedance 1.5
Source: https://docs.hoox.video/api-reference/assets/video/bytedance/seedance-1.5

ByteDance · `seedance-1.5` · video

## Identifier

Use the model identifier `seedance-1.5` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–1 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `16:9`) |
| Resolutions | `480p`, `720p`, `1080p` (default `720p`) |
| Durations (seconds) | `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12` (default `5`) |
| Audio | no |
| Max prompt length | 3000 chars |

## Inputs

Pass reference media in the `references` array (0–1 item). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `false` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |
| `camera_fixed` | boolean | `false` | no | Lock the camera: the shot stays static and only the subject moves. |

## Pricing

Default parameters (5s at `720p`): **\~2.6 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "seedance-1.5",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Seedance 2.0
Source: https://docs.hoox.video/api-reference/assets/video/bytedance/seedance-2.0

ByteDance · `seedance-2.0` · video

## Identifier

Use the model identifier `seedance-2.0` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–12 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `16:9`) |
| Resolutions | `480p`, `720p`, `1080p` (default `1080p`) |
| Durations (seconds) | `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `5`) |
| Audio | yes |
| Max prompt length | 3000 chars |
| Required plans | `PRO`, `ENTREPRISE` |

## Inputs

Pass reference media in the `references` array (0–12 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |
| `forceReferenceMode` | boolean | `false` | no | Use the attached media as subject/style references instead of the video's first frame. Reference mode turns on by itself from 3 references, or as soon as a video or an audio is attached; set this to get it with fewer — one reference is enough. |

## Pricing

Default parameters (5s at `1080p`): **\~34.05 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "seedance-2.0",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "1080p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Seedance 2.0 Fast
Source: https://docs.hoox.video/api-reference/assets/video/bytedance/seedance-2.0-fast

ByteDance · `seedance-2.0-fast` · video

## Identifier

Use the model identifier `seedance-2.0-fast` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–12 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `16:9`) |
| Resolutions | `480p`, `720p` (default `720p`) |
| Durations (seconds) | `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `5`) |
| Audio | yes |
| Max prompt length | 3000 chars |
| Required plans | `PRO`, `ENTREPRISE` |

## Inputs

Pass reference media in the `references` array (0–12 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |
| `forceReferenceMode` | boolean | `false` | no | Use the attached media as subject/style references instead of the video's first frame. Reference mode turns on by itself from 3 references, or as soon as a video or an audio is attached; set this to get it with fewer — one reference is enough. |

## Pricing

Default parameters (5s at `720p`): **\~12.1 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "seedance-2.0-fast",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Seedance 2.0 UGC
Source: https://docs.hoox.video/api-reference/assets/video/bytedance/seedance-2.0-ugc

ByteDance · `seedance-2.0-ugc` · video

## Identifier

Use the model identifier `seedance-2.0-ugc` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1–9 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `16:9`) |
| Resolutions | `480p`, `720p`, `1080p` (default `1080p`) |
| Durations (seconds) | `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` |
| Audio | yes |
| Max prompt length | 3000 chars |
| Required plans | `PRO`, `ENTREPRISE` |

## Inputs

Pass reference media in the `references` array (1–9 items). At least 1 reference is required. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (`1080p`): **\~34.05 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "seedance-2.0-ugc",
  "prompt": "Describe what you want to generate",
  "references": [
    {
      "url": "https://example.com/reference.jpg"
    }
  ],
  "aspect_ratio": "16:9",
  "resolution": "1080p"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Seedance 2.5
Source: https://docs.hoox.video/api-reference/assets/video/bytedance/seedance-2.5

ByteDance · `seedance-2.5` · video

## Identifier

Use the model identifier `seedance-2.5` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–50 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `16:9`) |
| Resolutions | `480p`, `720p`, `1080p` (default `720p`) |
| Durations (seconds) | `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30` (default `5`) |
| Audio | yes |
| Max prompt length | 3000 chars |
| Required plans | `PRO`, `ENTREPRISE` |

## Inputs

Pass reference media in the `references` array (0–50 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |
| `forceReferenceMode` | boolean | `false` | no | Use the attached media as subject/style references instead of the video's first frame. Reference mode turns on by itself from 3 references, or as soon as a video or an audio is attached; set this to get it with fewer — one reference is enough. |

## Pricing

Default parameters (5s at `720p`): **\~23.65 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "seedance-2.5",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Flux 3
Source: https://docs.hoox.video/api-reference/assets/video/flux/flux-3-video

Flux · `flux-3-video` · video

## Identifier

Use the model identifier `flux-3-video` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `9:16`) |
| Resolutions | `720p`, `1080p` (default `720p`) |
| Durations (seconds) | `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20` (default `5`) |
| Audio | yes |
| Tags | `new` |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s at `720p`): **\~8.5 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "flux-3-video",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Flux 3 Draft
Source: https://docs.hoox.video/api-reference/assets/video/flux/flux-3-video-draft

Flux · `flux-3-video-draft` · video

## Identifier

Use the model identifier `flux-3-video-draft` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–10 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `9:16`) |
| Durations (seconds) | `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20` (default `5`) |
| Audio | yes |
| Tags | `new` |

## Inputs

Pass reference media in the `references` array (0–10 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s): **\~3 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "flux-3-video-draft",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Flux 3 Edit
Source: https://docs.hoox.video/api-reference/assets/video/flux/flux-3-video-edit

Flux · `flux-3-video-edit` · video

## Identifier

Use the model identifier `flux-3-video-edit` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Input types | `video` |
| Max prompt length | 4096 chars |
| Tags | `video-edit` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `source_video` | video | yes | Video to edit. The prompt describes the modifications to apply. MP4 under 15 seconds and 50 MB. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Pricing

Default parameters: **\~4.5 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "flux-3-video-edit",
  "prompt": "Describe what you want to generate",
  "source_video": {
    "url": "https://example.com/reference.mp4"
  }
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Flux 3 Extend
Source: https://docs.hoox.video/api-reference/assets/video/flux/flux-3-video-extend

Flux · `flux-3-video-extend` · video

## Identifier

Use the model identifier `flux-3-video-extend` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Input types | `video` |
| Resolutions | `720p`, `1080p` (default `720p`) |
| Durations (seconds) | `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20` (default `5`) |
| Audio | yes |
| Tags | `extend` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `source_video` | video | yes | Video to continue. The result holds only the new footage, starting on its last frame. MP4 under 15 seconds and 50 MB. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | no | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s at `720p`): **\~20.5 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "flux-3-video-extend",
  "prompt": "Describe what you want to generate",
  "source_video": {
    "url": "https://example.com/reference.mp4"
  },
  "resolution": "720p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Gemini Omni 1.1
Source: https://docs.hoox.video/api-reference/assets/video/google/gemini-omni-video

Google · `gemini-omni-video` · video

## Identifier

Use the model identifier `gemini-omni-video` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–5 |
| Aspect ratios | `16:9`, `9:16` (default `9:16`) |
| Resolutions | `720p`, `1080p`, `4k` (default `1080p`) |
| Durations (seconds) | `4`, `6`, `8`, `10` (default `8`) |
| Audio | yes |

## Inputs

Pass reference media in the `references` array (0–5 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `forceReferenceMode` | boolean | `false` | no | Use the attached media as subject/style references instead of the video's first frame. Reference mode turns on by itself from 2 images; set this to get it with fewer — one reference is enough. |

## Pricing

Default parameters (8s at `1080p`): **\~12 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "gemini-omni-video",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "1080p",
  "duration": 8
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Veo 3.1 Lite
Source: https://docs.hoox.video/api-reference/assets/video/google/veo-3.1-lite

Google · `veo-3.1-lite` · video

## Identifier

Use the model identifier `veo-3.1-lite` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–1 |
| Aspect ratios | `16:9`, `9:16` (default `9:16`) |
| Resolutions | `720p`, `1080p` (default `720p`) |
| Durations (seconds) | `4`, `6`, `8` (default `8`) |
| Audio | yes |

## Inputs

Pass reference media in the `references` array (0–1 item). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (8s at `720p`): **\~4 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "veo-3.1-lite",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "duration": 8
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Hoox Upscale
Source: https://docs.hoox.video/api-reference/assets/video/hoox/hoox-upscale

Hoox · `hoox-upscale` · video

Raises a video to a target resolution and frame rate, keeping its audio. Hoox picks the engine: frame interpolation (RIFE) when only the frame rate goes up, the ByteDance upscaler when the resolution does. The output never goes below the source resolution, and a request that changes nothing is rejected. Billed per second of source video, at the output resolution and frame rate.

## Identifier

Use the model identifier `hoox-upscale` in the `model` field when calling [`/asset/start`](/api-reference/assets/start). This model takes no `prompt`.

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Input types | `video` |
| Resolutions | `1080p`, `2k`, `4k` (default `1080p`) |
| Audio | yes |
| Tags | `upscale` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `source_video` | video | yes | Video to upscale. Its resolution, frame rate and duration are read from the file. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `fps` | select | `60` | yes | Output frame rate. When the resolution does not go up, it must be above the source frame rate. Options: `30`, `60`, `120`. |

## Pricing

Billed per second of source video, in credits, at the output resolution and frame rate. The output resolution is never below the source's.

| Resolution | 30 fps | 60 fps | 120 fps |
| - | - | - | - |
| `1080p` | 0.072 | 0.144 | 0.288 |
| `2k` | 0.144 | 0.288 | 0.576 |
| `4k` | 0.288 | 0.576 | 1.152 |

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "hoox-upscale",
  "source_video": {
    "url": "https://example.com/reference.mp4"
  },
  "resolution": "1080p"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 2.6 Motion Control
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-motion-control

Kling · `kling-motion-control` · video

## Identifier

Use the model identifier `kling-motion-control` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 2 |
| Input types | `image` + `video` |
| Audio | yes |
| Max prompt length | 2500 chars |
| Tags | `motion-control` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `start_image` | image | yes | Subject image. The model transfers the motion from the reference video onto this image. |
| `motion_video` | video | yes | Reference video whose motion pattern is applied to the start image. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `keepOriginalSound` | boolean | `true` | no | Keep the source video soundtrack in the result instead of returning a silent clip. |

## Pricing

Default parameters: **\~7 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-motion-control",
  "prompt": "Describe what you want to generate",
  "start_image": {
    "url": "https://example.com/reference.jpg"
  },
  "motion_video": {
    "url": "https://example.com/reference.mp4"
  }
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 2.6 Motion Control Pro
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-motion-control-pro

Kling · `kling-motion-control-pro` · video

## Identifier

Use the model identifier `kling-motion-control-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 2 |
| Input types | `image` + `video` |
| Audio | yes |
| Max prompt length | 2500 chars |
| Tags | `motion-control` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `start_image` | image | yes | Subject image. The model transfers the motion from the reference video onto this image. |
| `motion_video` | video | yes | Reference video whose motion pattern is applied to the start image. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `keepOriginalSound` | boolean | `true` | no | Keep the source video soundtrack in the result instead of returning a silent clip. |

## Pricing

Default parameters: **\~11.2 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-motion-control-pro",
  "prompt": "Describe what you want to generate",
  "start_image": {
    "url": "https://example.com/reference.jpg"
  },
  "motion_video": {
    "url": "https://example.com/reference.mp4"
  }
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling O3 Edit Pro
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-o3-edit-pro

Kling · `kling-o3-edit-pro` · video

## Identifier

Use the model identifier `kling-o3-edit-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Input types | `video` |
| Audio | yes |
| Max prompt length | 2500 chars |
| Tags | `video-edit` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `source_video` | video | yes | Video to edit. The prompt describes the modifications to apply. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `keepAudio` | boolean | `true` | no | Keep the source video soundtrack in the edited result instead of returning a silent clip. |

## Pricing

Default parameters: **\~16.8 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-o3-edit-pro",
  "prompt": "Describe what you want to generate",
  "source_video": {
    "url": "https://example.com/reference.mp4"
  }
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling O3 Edit Standard
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-o3-edit-standard

Kling · `kling-o3-edit-standard` · video

## Identifier

Use the model identifier `kling-o3-edit-standard` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Input types | `video` |
| Audio | yes |
| Max prompt length | 2500 chars |
| Tags | `video-edit` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `source_video` | video | yes | Video to edit. The prompt describes the modifications to apply. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `keepAudio` | boolean | `true` | no | Keep the source video soundtrack in the edited result instead of returning a silent clip. |

## Pricing

Default parameters: **\~12.6 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-o3-edit-standard",
  "prompt": "Describe what you want to generate",
  "source_video": {
    "url": "https://example.com/reference.mp4"
  }
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling O3 Pro
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-o3-pro

Kling · `kling-o3-pro` · video

## Identifier

Use the model identifier `kling-o3-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–2 |
| Input types | `image` + `image` |
| Aspect ratios | `16:9`, `9:16`, `1:1` (default `9:16`) |
| Durations (seconds) | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `5`) |
| Audio | yes |
| Max prompt length | 2500 chars |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `first_frame` | image | no | Image used as the first frame of the generated video. Omit for pure text-to-video. |
| `last_frame` | image | no | Image used as the last frame of the generated video. Requires first\_frame — generates a transition from the first frame to this one. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s): **\~7 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-o3-pro",
  "prompt": "Describe what you want to generate",
  "first_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "last_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "aspect_ratio": "9:16",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling O3 Standard
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-o3-standard

Kling · `kling-o3-standard` · video

## Identifier

Use the model identifier `kling-o3-standard` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–2 |
| Input types | `image` + `image` |
| Aspect ratios | `16:9`, `9:16`, `1:1` (default `9:16`) |
| Durations (seconds) | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `5`) |
| Audio | yes |
| Max prompt length | 2500 chars |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `first_frame` | image | no | Image used as the first frame of the generated video. Omit for pure text-to-video. |
| `last_frame` | image | no | Image used as the last frame of the generated video. Requires first\_frame — generates a transition from the first frame to this one. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s): **\~5.6 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-o3-standard",
  "prompt": "Describe what you want to generate",
  "first_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "last_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "aspect_ratio": "9:16",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 2.6 Pro
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-pro

Kling · `kling-pro` · video

## Identifier

Use the model identifier `kling-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–2 |
| Input types | `image` + `image` |
| Aspect ratios | `16:9`, `9:16`, `1:1` (default `9:16`) |
| Durations (seconds) | `5`, `10` (default `5`) |
| Audio | yes |
| Max prompt length | 2500 chars |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `start_image` | image | no | First frame of the video. Omit for pure text-to-video. |
| `end_image` | image | no | Last frame of the video. Requires start\_image — generates a transition from the start frame to this one. Audio generation is disabled automatically when an end frame is used. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s): **\~7 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-pro",
  "prompt": "Describe what you want to generate",
  "start_image": {
    "url": "https://example.com/reference.jpg"
  },
  "end_image": {
    "url": "https://example.com/reference.jpg"
  },
  "aspect_ratio": "9:16",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 2.5 Standard
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-standard

Kling · `kling-standard` · video

## Identifier

Use the model identifier `kling-standard` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Aspect ratios | `16:9`, `9:16`, `1:1` (default `9:16`) |
| Durations (seconds) | `5`, `10` (default `5`) |
| Audio | no |
| Max prompt length | 2500 chars |

## Inputs

Pass reference media in the `references` array (1 item). At least 1 reference is required. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `false` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s): **\~2.1 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-standard",
  "prompt": "Describe what you want to generate",
  "references": [
    {
      "url": "https://example.com/reference.jpg"
    }
  ],
  "aspect_ratio": "9:16",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 3.0 Motion Control Pro
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-v3-motion-pro

Kling · `kling-v3-motion-pro` · video

## Identifier

Use the model identifier `kling-v3-motion-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 2 |
| Input types | `image` + `video` |
| Audio | yes |
| Max prompt length | 2500 chars |
| Tags | `motion-control` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `start_image` | image | yes | Subject image. The model transfers the motion from the reference video onto this image. |
| `motion_video` | video | yes | Reference video whose motion pattern is applied to the start image. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `keepOriginalSound` | boolean | `true` | no | Keep the source video soundtrack in the result instead of returning a silent clip. |

## Pricing

Default parameters: **\~16.8 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-v3-motion-pro",
  "prompt": "Describe what you want to generate",
  "start_image": {
    "url": "https://example.com/reference.jpg"
  },
  "motion_video": {
    "url": "https://example.com/reference.mp4"
  }
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 3.0 Motion Control
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-v3-motion-standard

Kling · `kling-v3-motion-standard` · video

## Identifier

Use the model identifier `kling-v3-motion-standard` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 2 |
| Input types | `image` + `video` |
| Audio | yes |
| Max prompt length | 2500 chars |
| Tags | `motion-control` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `start_image` | image | yes | Subject image. The model transfers the motion from the reference video onto this image. |
| `motion_video` | video | yes | Reference video whose motion pattern is applied to the start image. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `keepOriginalSound` | boolean | `true` | no | Keep the source video soundtrack in the result instead of returning a silent clip. |

## Pricing

Default parameters: **\~12.6 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-v3-motion-standard",
  "prompt": "Describe what you want to generate",
  "start_image": {
    "url": "https://example.com/reference.jpg"
  },
  "motion_video": {
    "url": "https://example.com/reference.mp4"
  }
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 3.0 Pro
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-v3-pro

Kling · `kling-v3-pro` · video

## Identifier

Use the model identifier `kling-v3-pro` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–2 |
| Input types | `image` + `image` |
| Aspect ratios | `16:9`, `9:16`, `1:1` (default `9:16`) |
| Durations (seconds) | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `5`) |
| Elements | up to 4, 2–4 images each |
| Audio | yes |
| Max prompt length | 2500 chars |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `first_frame` | image | no | Image used as the first frame of the generated video. Omit for pure text-to-video. |
| `last_frame` | image | no | Image used as the last frame of the generated video. Requires first\_frame — generates a transition from the first frame to this one. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Elements

Elements are named characters or objects you inject in the generation, each described by several images of the same subject. You then refer to them in the prompt with `@name`, so the model knows exactly which subject a sentence is about.

Pass up to **4** of them in the `elements` array:

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Alias used in the prompt as `@name`. Letters, digits and underscores only (max 32 chars). |
| `images` | array | yes | **2 to 4 images** of the same subject — frontal view first, then other angles. Each item takes one of `url`, `asset_id`, or `avatar_id`. |

Rules enforced by the API:

* Each element needs **at least 2 images**.
* The prompt **must reference every element** as `@name` — otherwise the element would be ignored and the generation charged for nothing.
* Names must be unique, and cannot be `refN` or `elementN` (reserved for the internal rewriting of prompt references).
* `first_frame` is required whenever you use elements.

### Example with elements

```json theme={null}
{
  "type": "video",
  "model": "kling-v3-pro",
  "prompt": "The woman from @hero picks up the mug and smiles at the camera",
  "first_frame": {
    "url": "https://example.com/first-frame.jpg"
  },
  "elements": [
    {
      "name": "hero",
      "images": [
        {
          "url": "https://example.com/hero-frontal.jpg"
        },
        {
          "url": "https://example.com/hero-side.jpg"
        }
      ]
    }
  ],
  "duration": 5
}
```

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s): **\~8.4 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-v3-pro",
  "prompt": "Describe what you want to generate",
  "first_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "last_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "aspect_ratio": "9:16",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Kling 3.0 Standard
Source: https://docs.hoox.video/api-reference/assets/video/kling/kling-v3-standard

Kling · `kling-v3-standard` · video

## Identifier

Use the model identifier `kling-v3-standard` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–2 |
| Input types | `image` + `image` |
| Aspect ratios | `16:9`, `9:16`, `1:1` (default `9:16`) |
| Durations (seconds) | `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `5`) |
| Elements | up to 4, 2–4 images each |
| Audio | yes |
| Max prompt length | 2500 chars |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `first_frame` | image | no | Image used as the first frame of the generated video. Omit for pure text-to-video. |
| `last_frame` | image | no | Image used as the last frame of the generated video. Requires first\_frame — generates a transition from the first frame to this one. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Elements

Elements are named characters or objects you inject in the generation, each described by several images of the same subject. You then refer to them in the prompt with `@name`, so the model knows exactly which subject a sentence is about.

Pass up to **4** of them in the `elements` array:

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Alias used in the prompt as `@name`. Letters, digits and underscores only (max 32 chars). |
| `images` | array | yes | **2 to 4 images** of the same subject — frontal view first, then other angles. Each item takes one of `url`, `asset_id`, or `avatar_id`. |

Rules enforced by the API:

* Each element needs **at least 2 images**.
* The prompt **must reference every element** as `@name` — otherwise the element would be ignored and the generation charged for nothing.
* Names must be unique, and cannot be `refN` or `elementN` (reserved for the internal rewriting of prompt references).
* `first_frame` is required whenever you use elements.

### Example with elements

```json theme={null}
{
  "type": "video",
  "model": "kling-v3-standard",
  "prompt": "The woman from @hero picks up the mug and smiles at the camera",
  "first_frame": {
    "url": "https://example.com/first-frame.jpg"
  },
  "elements": [
    {
      "name": "hero",
      "images": [
        {
          "url": "https://example.com/hero-frontal.jpg"
        },
        {
          "url": "https://example.com/hero-side.jpg"
        }
      ]
    }
  ],
  "duration": 5
}
```

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `generateAudio` | boolean | `true` | yes | Generate the native soundtrack (dialogue, ambience, effects) along with the video. |

## Pricing

Default parameters (5s): **\~6.3 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "kling-v3-standard",
  "prompt": "Describe what you want to generate",
  "first_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "last_frame": {
    "url": "https://example.com/reference.jpg"
  },
  "aspect_ratio": "9:16",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# MiniMax H3 Max
Source: https://docs.hoox.video/api-reference/assets/video/minimax/minimax-h3-max

MiniMax · `minimax-h3-max` · video

## Identifier

Use the model identifier `minimax-h3-max` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–12 |
| Aspect ratios | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` (default `9:16`) |
| Resolutions | `480p`, `768p` (default `768p`) |
| Durations (seconds) | `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `5`) |
| Audio | yes |

## Inputs

Pass reference media in the `references` array (0–12 items). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Custom settings

These keys go inside the `model_settings` object of the request body.

| Key | Type | Default | Affects cost | Description |
| - | - | - | - | - |
| `forceReferenceMode` | boolean | `false` | yes | Use the attached media as subject/style references instead of the video's first frame. Reference mode turns on by itself from 3 references, or as soon as a video or an audio is attached; set this to get it with fewer — one reference is enough. Reference mode is billed at its own rate, so this changes the price. |

## Pricing

Default parameters (5s at `768p`): **\~4 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "minimax-h3-max",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "768p",
  "duration": 5
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Grok Video
Source: https://docs.hoox.video/api-reference/assets/video/xai/grok-imagine-video

xAI Grok · `grok-imagine-video` · video

## Identifier

Use the model identifier `grok-imagine-video` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 0–1 |
| Aspect ratios | `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16` (default `9:16`) |
| Resolutions | `480p`, `720p` (default `720p`) |
| Durations (seconds) | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `6`) |
| Audio | no |

## Inputs

Pass reference media in the `references` array (0–1 item). Optional. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (6s at `720p`): **\~4.2 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "grok-imagine-video",
  "prompt": "Describe what you want to generate",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "duration": 6
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Grok Video 1.5
Source: https://docs.hoox.video/api-reference/assets/video/xai/grok-imagine-video-1.5

xAI Grok · `grok-imagine-video-1.5` · video

## Identifier

Use the model identifier `grok-imagine-video-1.5` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Aspect ratios | `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16` (default `9:16`) |
| Resolutions | `480p`, `720p`, `1080p` (default `720p`) |
| Durations (seconds) | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15` (default `6`) |
| Audio | yes |
| Max prompt length | 4096 chars |

## Inputs

Pass reference media in the `references` array (1 item). At least 1 reference is required. Each item accepts exactly one of:

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

## Pricing

Default parameters (6s at `720p`): **\~8.4 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "grok-imagine-video-1.5",
  "prompt": "Describe what you want to generate",
  "references": [
    {
      "url": "https://example.com/reference.jpg"
    }
  ],
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "duration": 6
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Grok Video Edit
Source: https://docs.hoox.video/api-reference/assets/video/xai/grok-imagine-video-edit

xAI Grok · `grok-imagine-video-edit` · video

## Identifier

Use the model identifier `grok-imagine-video-edit` in the `model` field when calling [`/asset/start`](/api-reference/assets/start).

## Capabilities

| Property | Value |
| - | - |
| Reference inputs | 1 |
| Input types | `video` |
| Aspect ratios | `16:9`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `9:16` (default `16:9`) |
| Resolutions | `480p`, `720p` (default `720p`) |
| Audio | no |
| Tags | `video-edit` |

## Inputs

This model takes **named media inputs**. Pass each one as a top-level field in the request body. Each field accepts exactly one of `url`, `asset_id`, or `avatar_id`.

| Field | Type | Required | Description |
| - | - | - | - |
| `source_video` | video | yes | Video to edit. The prompt describes the modifications to apply. |

* `url` — a direct, publicly accessible file URL
* `asset_id` — the ID of an existing asset in your Hoox space (e.g. a previous generation)
* `avatar_id` — the ID of an avatar defined in your Hoox space

A positional `references` array is also accepted, mapped onto the slots in the order above.

## Pricing

Default parameters (`720p`): **\~6.4 credits / generation**.

For exact pricing with your own parameters, call [`/asset/pricing`](/api-reference/assets/pricing) with the `model` and any parameters that affect cost.

## Example request

```json theme={null}
{
  "type": "video",
  "model": "grok-imagine-video-edit",
  "prompt": "Describe what you want to generate",
  "source_video": {
    "url": "https://example.com/reference.mp4"
  },
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
```

See [`/asset/start`](/api-reference/assets/start) for the full request/response reference, error codes, and code samples in cURL / Python / JavaScript.


# Create Avatar
Source: https://docs.hoox.video/api-reference/avatars/create

POST https://app.hoox.video/api/public/v1/avatar/create
Create an avatar from a prompt or from image URLs. If a prompt is provided, it takes priority.

## Overview

This endpoint creates a new avatar with one or more looks. You can create an avatar in two ways:

1. **Prompt-based creation**: Provide a text prompt and style to generate an avatar using AI. The prompt takes priority if provided.
2. **Image-based creation**: Provide image URLs that will be used as-is for the avatar looks (not as reference images).

<Warning>
  When using images, they are used directly as the avatar looks, not as reference images for generation.
</Warning>

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField type="string">
  Text prompt describing the avatar to generate. If provided, prompt-based generation takes priority over images.
</ParamField>

<ParamField type="string">
  Avatar style. Available options: `iphone`, `selfie`, `podcast`, `car`, `conference`. Optional, defaults to `iphone`.
</ParamField>

<ParamField type="string">
  Image format: `vertical` (9:16) or `horizontal` (16:9). Only used for prompt-based generation.
</ParamField>

<ParamField type="string">
  Custom name for the avatar.
</ParamField>

<ParamField type="string">
  Place or context for the avatar (e.g., "office", "studio").
</ParamField>

<ParamField type="array">
  Array of image URLs. These images are used as-is for the avatar looks (not as reference). Only used if no prompt is provided.
</ParamField>

<ParamField type="array">
  Array of image URLs to use as reference elements during generation. These images guide the AI to incorporate specific visual elements (logos, products, objects) into the generated avatar. Only used with prompt-based generation.
</ParamField>

<ParamField type="string">
  Output image resolution: `2K` or `4K`. Optional, defaults to `2K`. Note that `4K` generation costs more credits.
</ParamField>

<ParamField type="string">
  URL to receive webhook notifications when generation completes.
</ParamField>

## Response

<ResponseField name="avatar_id" type="string">
  Unique identifier for the created avatar.
</ResponseField>

<ResponseField name="look_id" type="string">
  Unique identifier for the first look of the avatar. For prompt-based generation, this look will be in "pending" status initially.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/avatar/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Professional portrait of a CTO, smiling, natural lighting",
      "style": "selfie",
      "format": "vertical",
      "name": "Alex",
      "place": "office",
      "resolution": "2K",
      "webhook_url": "https://example.com/webhooks/avatar"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/avatar/create"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "prompt": "Professional portrait of a CTO, smiling, natural lighting",
      "style": "selfie",
      "format": "vertical",
      "name": "Alex",
      "place": "office",
      "resolution": "2K",
      "webhook_url": "https://example.com/webhooks/avatar"
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/avatar/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Professional portrait of a CTO, smiling, natural lighting",
      style: "selfie",
      format: "vertical",
      name: "Alex",
      place: "office",
      resolution: "2K",
      webhook_url: "https://example.com/webhooks/avatar"
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```bash With Element Images theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/avatar/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Professional woman holding a product, office background",
      "style": "selfie",
      "format": "vertical",
      "elementImages": [
        "https://example.com/logo.png",
        "https://example.com/product.jpg"
      ],
      "resolution": "4K",
      "webhook_url": "https://example.com/webhooks/avatar"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "avatar_id": "avtr_123",
    "look_id": "look_abc"
  }
  ```

  ```json Error 400 - Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "INVALID_VALUE",
        "message": "prompt is required",
        "field": "prompt"
      }
    ]
  }
  ```

  ```json Error 402 - Insufficient Credits theme={null}
  {
    "error": "Insufficient credits",
    "required": 2,
    "available": 1
  }
  ```
</ResponseExample>

## Creation Methods

### 1. Prompt-based Creation

Provide a `prompt` (and optionally `style`, defaulting to "iphone"). The AI will generate the avatar image. The first look will start in "pending" status and become "ready" once generation completes.

**With Element Images**: You can also provide `elementImages` (or `elements`) to guide the AI generation with specific visual references. This is useful for incorporating logos, products, or specific objects into the generated avatar.

### 2. Image-based Creation

Provide an `images` array with image URLs. These images are used directly as the avatar looks (not as reference). The looks are immediately available with status "ready".

## Credit Costs

* **Prompt-based creation (2K)**: 2 credits
* **Prompt-based creation (4K)**: 4 credits
* **Image-based creation**: Free (no credits charged)

## Next Steps

1. **Check Status**: Use `/avatar/status` endpoint to monitor the generation progress
2. **Edit Avatar**: Use `/avatar/edit` endpoint to create new looks from existing ones

## Error Codes

* `INVALID_VALUE`: Invalid parameter value (webhook\_url, style, or images)
* `INSUFFICIENT_CREDITS`: Not enough credits to create the avatar
* `AVATAR_LIMIT_REACHED`: Maximum number of avatars reached for your plan
* `SPACE_NOT_FOUND`: Space doesn't exist
* `FAILED_TO_PERSIST`: Error saving avatar to database
* `GENERATION_FAILED`: Avatar generation failed (async error sent via webhook)


# Edit Avatar Look
Source: https://docs.hoox.video/api-reference/avatars/edit

POST https://app.hoox.video/api/public/v1/avatar/edit
Create a new look for an existing avatar by editing from an existing look with a prompt

## Overview

This endpoint creates a new look for an existing avatar by editing a source look using AI. The source look is not modified - a new look is created based on it.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField type="string">
  Unique identifier of the avatar to edit.
</ParamField>

<ParamField type="string">
  Unique identifier of the source look to use as base for editing.
</ParamField>

<ParamField type="string">
  Text prompt describing how to edit the look.
</ParamField>

<ParamField type="string">
  Image format: `vertical` (9:16) or `horizontal` (16:9). Defaults to `vertical`.
</ParamField>

<ParamField type="string">
  Avatar style to apply: `selfie`, `podcast`, `car`, `iphone`, `conference`, or `raw`.
</ParamField>

<ParamField type="array">
  Additional image URLs to use for editing. The source look's image is automatically added first if available.
</ParamField>

<ParamField type="string">
  Output image resolution: `2K` or `4K`. Optional, defaults to `2K`. Note that `4K` generation costs more credits.
</ParamField>

<ParamField type="string">
  URL to receive webhook notifications when generation completes.
</ParamField>

## Response

<ResponseField name="avatar_id" type="string">
  Unique identifier of the avatar.
</ResponseField>

<ResponseField name="look_id" type="string">
  Unique identifier of the newly created look. This look starts in "pending" status.
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/avatar/edit" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "avatar_id": "avtr_123",
      "look_id": "look_src",
      "prompt": "Add my product in his hand",
      "format": "vertical",
      "style": "iphone",
      "imageUrls": ["https://cdn.example.com/extra.jpg"],
      "resolution": "2K",
      "webhook_url": "https://example.com/webhooks/avatar-edit"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/avatar/edit"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "avatar_id": "avtr_123",
      "look_id": "look_src",
      "prompt": "Sharper portrait, cinematic lighting",
      "format": "vertical",
      "style": "iphone",
      "imageUrls": ["https://cdn.example.com/extra.jpg"],
      "resolution": "2K",
      "webhook_url": "https://example.com/webhooks/avatar-edit"
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/avatar/edit', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      avatar_id: "avtr_123",
      look_id: "look_src",
      prompt: "Sharper portrait, cinematic lighting",
      format: "vertical",
      style: "iphone",
      imageUrls: ["https://cdn.example.com/extra.jpg"],
      resolution: "2K",
      webhook_url: "https://example.com/webhooks/avatar-edit"
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "avatar_id": "avtr_123",
    "look_id": "look_new"
  }
  ```

  ```json Error 400 - Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "MISSING_AVATAR_ID",
        "message": "avatar_id is required",
        "field": "avatar_id"
      }
    ]
  }
  ```

  ```json Error 404 - Avatar Not Found theme={null}
  {
    "error": "Avatar not found"
  }
  ```

  ```json Error 402 - Insufficient Credits theme={null}
  {
    "error": "Insufficient credits",
    "required": 2,
    "available": 1
  }
  ```
</ResponseExample>

## Credit Costs

* **Base cost (2K)**: 2 credits
* **Base cost (4K)**: 4 credits

## Next Steps

1. **Check Status**: Use `/avatar/status` endpoint to monitor the generation progress
2. **List Looks**: Use `/avatar/list` to see all available looks for your avatar

## Error Codes

* `MISSING_AVATAR_ID`: avatar\_id parameter is required
* `MISSING_LOOK_ID`: look\_id parameter is required
* `INVALID_WEBHOOK_URL`: webhook\_url must be a valid URL
* `MISSING_PROMPT`: prompt parameter is required
* `NO_IMAGE_AVAILABLE`: No image available (source look has no thumbnail and images array is empty)
* `INSUFFICIENT_CREDITS`: Not enough credits to edit the avatar
* `SPACE_NOT_FOUND`: Space doesn't exist
* `AVATAR_NOT_FOUND`: Avatar with specified ID doesn't exist
* `LOOK_NOT_FOUND`: Look with specified ID doesn't exist
* `FAILED_TO_PERSIST`: Error saving new look to database
* `GENERATION_FAILED`: Look generation failed (async error sent via webhook)


# Get Avatar
Source: https://docs.hoox.video/api-reference/avatars/get

GET https://app.hoox.video/api/public/v1/avatar/{avatar_id}
Retrieve details of a specific avatar by its ID

## Overview

This endpoint retrieves details for a specific avatar by its `id`. Results can come from your space (custom avatars) or from the public catalog. The response includes all looks associated with the avatar.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Path Parameters

<ParamField type="string">
  The unique identifier of the avatar to retrieve.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the avatar.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the avatar.
</ResponseField>

<ResponseField name="gender" type="string">
  Gender of the avatar: `male` or `female`.
</ResponseField>

<ResponseField name="age" type="string">
  Age of the avatar.
</ResponseField>

<ResponseField name="age_range" type="string">
  Avatar age range.
</ResponseField>

<ResponseField name="ethnicity" type="string">
  Avatar ethnicity.
</ResponseField>

<ResponseField name="hair_color" type="string">
  Avatar hair color.
</ResponseField>

<ResponseField name="thumbnail" type="string">
  URL of the avatar thumbnail image.
</ResponseField>

<ResponseField name="looks" type="array">
  Array of looks associated with this avatar.

  <Expandable title="Look object properties">
    <ResponseField name="id" type="string">
      Unique identifier of the look.
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the look.
    </ResponseField>

    <ResponseField name="place" type="string">
      Place or context of the look.
    </ResponseField>

    <ResponseField name="accessories" type="array">
      Visible accessories or props in the look.
    </ResponseField>

    <ResponseField name="action" type="string">
      Main action detected for the look.
    </ResponseField>

    <ResponseField name="emotion" type="string">
      Emotion or mood detected for the look.
    </ResponseField>

    <ResponseField name="selfie" type="boolean">
      Whether the look is a selfie-style shot.
    </ResponseField>

    <ResponseField name="format" type="string">
      Image format: `vertical` or `horizontal`.
    </ResponseField>

    <ResponseField name="thumbnail" type="string">
      URL of the look thumbnail.
    </ResponseField>

    <ResponseField name="preview" type="string">
      Preview URL if available, otherwise `null`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `ready`, `pending`, or `error`.
    </ResponseField>

    <ResponseField name="model_available" type="array">
      Available models for this look. Possible values: `standard`, `premium`, `ultra`, `veo-3-fast`, `veo-3-lite`, `omni-flash`, `ora-lite`, `ora-standard`, `ora-pro`, `seedance-2-fast`, `seedance-2-5`, `seedance-2-5-1080p`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  Creation timestamp if available, otherwise `null`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/avatar/avtr_abc123" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/avatar/avtr_abc123"
  headers = {"Authorization": "Bearer your_api_key"}
  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/avatar/avtr_abc123', {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "avtr_abc123",
    "name": "Alex",
    "gender": "male",
    "age": "30",
    "age_range": "adult",
    "ethnicity": "white-western-european",
    "hair_color": "brown",
    "thumbnail": "https://cdn.example.com/avatar-thumbnail.jpg",
    "looks": [
      {
        "id": "look_123",
        "name": "Office Look",
        "place": "office",
        "accessories": ["laptop"],
        "action": "working",
        "emotion": "focused",
        "selfie": false,
        "format": "vertical",
        "thumbnail": "https://cdn.example.com/look-thumbnail.jpg",
        "preview": null,
        "status": "ready",
        "model_available": ["premium", "ultra", "veo-3-fast", "veo-3-lite", "omni-flash", "ora-lite", "ora-standard", "ora-pro", "seedance-2-fast", "seedance-2-5", "seedance-2-5-1080p"]
      },
      {
        "id": "look_456",
        "name": "Studio Look",
        "place": "studio",
        "accessories": ["microphone"],
        "action": "presenting",
        "emotion": "confident",
        "selfie": false,
        "format": "vertical",
        "thumbnail": "https://cdn.example.com/look2-thumbnail.jpg",
        "preview": null,
        "status": "ready",
        "model_available": ["premium", "ultra", "veo-3-fast", "veo-3-lite", "omni-flash", "ora-lite", "ora-standard", "ora-pro", "seedance-2-fast", "seedance-2-5", "seedance-2-5-1080p"]
      }
    ],
    "created_at": "2024-01-15T10:30:00Z"
  }
  ```

  ```json Error 404 - Not Found theme={null}
  {
    "error": "Avatar not found",
    "details": [
      {
        "code": "NOT_FOUND",
        "message": "Avatar with id \"avtr_abc123\" not found"
      }
    ]
  }
  ```
</ResponseExample>


# Get Avatar Look
Source: https://docs.hoox.video/api-reference/avatars/get-look

GET https://app.hoox.video/api/public/v1/avatar/{avatar_id}/look/{look_id}
Retrieve details of a specific look for an avatar

## Overview

This endpoint retrieves details for a specific look of an avatar. Use this to get full information about a particular look including available models and generation status.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Path Parameters

<ParamField type="string">
  The unique identifier of the avatar.
</ParamField>

<ParamField type="string">
  The unique identifier of the look to retrieve.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the look.
</ResponseField>

<ResponseField name="avatar_id" type="string">
  Unique identifier of the parent avatar.
</ResponseField>

<ResponseField name="avatar_name" type="string">
  Name of the avatar.
</ResponseField>

<ResponseField name="look_name" type="string">
  Name of the look.
</ResponseField>

<ResponseField name="gender" type="string">
  Gender of the avatar: `male` or `female`.
</ResponseField>

<ResponseField name="age_range" type="string">
  Avatar age range.
</ResponseField>

<ResponseField name="ethnicity" type="string">
  Avatar ethnicity.
</ResponseField>

<ResponseField name="hair_color" type="string">
  Avatar hair color.
</ResponseField>

<ResponseField name="place" type="string">
  Place or context of the look (e.g., "studio", "office").
</ResponseField>

<ResponseField name="accessories" type="array">
  Visible accessories or props in the look.
</ResponseField>

<ResponseField name="action" type="string">
  Main action detected for the look.
</ResponseField>

<ResponseField name="emotion" type="string">
  Emotion or mood detected for the look.
</ResponseField>

<ResponseField name="selfie" type="boolean">
  Whether the look is a selfie-style shot.
</ResponseField>

<ResponseField name="format" type="string">
  Image format: `vertical` or `horizontal`.
</ResponseField>

<ResponseField name="thumbnail" type="string">
  URL of the look thumbnail image.
</ResponseField>

<ResponseField name="preview" type="string">
  Preview URL if available, otherwise `null`.
</ResponseField>

<ResponseField name="model_available" type="array">
  Available models for this look. Possible values: `standard`, `premium`, `ultra`, `veo-3-fast`, `veo-3-lite`, `omni-flash`, `ora-lite`, `ora-standard`, `ora-pro`, `seedance-2-fast`, `seedance-2-5`, `seedance-2-5-1080p`.
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `ready`, `pending`, or `error`.
</ResponseField>

<ResponseField name="error_message" type="string">
  Error message if status is `error`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/avatar/avtr_abc123/look/look_123" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/avatar/avtr_abc123/look/look_123"
  headers = {"Authorization": "Bearer your_api_key"}
  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/avatar/avtr_abc123/look/look_123', {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "look_123",
    "avatar_id": "avtr_abc123",
    "avatar_name": "Alex",
    "look_name": "Office Look",
    "gender": "male",
    "age_range": "adult",
    "ethnicity": "white-western-european",
    "hair_color": "brown",
    "place": "office",
    "accessories": ["laptop"],
    "action": "working",
    "emotion": "focused",
    "selfie": false,
    "format": "vertical",
    "thumbnail": "https://cdn.example.com/thumbnail.jpg",
    "preview": null,
    "model_available": ["premium", "ultra", "veo-3-fast", "veo-3-lite", "omni-flash", "ora-lite", "ora-standard", "ora-pro", "seedance-2-fast", "seedance-2-5", "seedance-2-5-1080p"],
    "status": "ready",
    "error_message": null
  }
  ```

  ```json Error 404 - Avatar Not Found theme={null}
  {
    "error": "Avatar not found",
    "details": [
      {
        "code": "NOT_FOUND",
        "message": "Avatar with id \"avtr_abc123\" not found"
      }
    ]
  }
  ```

  ```json Error 404 - Look Not Found theme={null}
  {
    "error": "Avatar look not found",
    "details": [
      {
        "code": "NOT_FOUND",
        "message": "Look with id \"look_123\" not found for avatar \"avtr_abc123\""
      }
    ]
  }
  ```
</ResponseExample>


# List Avatars
Source: https://docs.hoox.video/api-reference/avatars/list

GET https://app.hoox.video/api/public/v1/avatar/list
Retrieve available avatar looks for your space and public catalog

## Overview

This endpoint retrieves a list of available avatar looks. It returns looks from your space first (if any), followed by looks from the public catalog. Results can be filtered by avatar and look metadata.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Query Parameters

<ParamField type="enum">
  Filter by gender. Available values: `male`, `female`.
</ParamField>

<ParamField type="enum">
  Filter by avatar age range. Accepts a comma-separated list. Available values: `senior`, `adult`, `young_adult`, `adolescent`.
</ParamField>

<ParamField type="enum">
  Filter by avatar ethnicity. Accepts a comma-separated list. Available values: `black-or-african-american`, `white-western-european`, `white-eastern-european`, `hispanic-or-latino`, `middle-eastern-or-north-african`, `east-asian`, `southeast-asian`, `south-asian`.
</ParamField>

<ParamField type="enum">
  Filter by hair color. Accepts a comma-separated list. Available values: `black`, `brown`, `blonde`, `red`, `gray`, `white`, `bald`.
</ParamField>

<ParamField type="enum">
  Filter by look place. Accepts a comma-separated list. Available values: `bathroom`, `beach`, `car`, `bedroom`, `podcast`, `home`, `office`, `gym`, `outdoor`, `kitchen`, `restaurant`, `studio`, `street`, `classroom`, `hospital`, `hotel`, `park`, `store`, `cafe`, `other`.
</ParamField>

<ParamField type="boolean">
  Filter by selfie looks. Use `true` or `false`.
</ParamField>

<ParamField type="enum">
  Filter by look action. Accepts a comma-separated list. Available values: `working`, `eating`, `drinking`, `cooking`, `exercising`, `reading`, `driving`, `listening_to_music`, `getting_a_haircut`, `presenting`, `calling`, `relaxing`, `shopping`, `traveling`, `applying_skincare`.
</ParamField>

<ParamField type="enum">
  Filter by look emotion. Accepts a comma-separated list. Available values: `happy`, `calm`, `focused`, `relaxed`, `neutral`, `excited`, `confident`, `sad`, `skeptical`, `bored`, `engaged`.
</ParamField>

<ParamField type="enum">
  Filter by visible accessories. Accepts a comma-separated list. Available values: `microphone`, `laptop`, `phone`, `headphones`, `earbuds`, `glasses`, `watch`, `drink`, `skincare`, `book`, `bag`, `camera`, `pillow`, `earrings`, `necklace`, `bracelet`, `ring`.
</ParamField>

<ParamField type="boolean">
  If `true`, returns only public catalog avatars (excludes custom space avatars). Defaults to `false` (returns both space and public avatars).
</ParamField>

## Response

Returns an array of avatar look objects.

<ResponseField name="id" type="string">
  Unique identifier of the look.
</ResponseField>

<ResponseField name="avatar_id" type="string">
  Unique identifier of the parent avatar.
</ResponseField>

<ResponseField name="avatar_name" type="string">
  Name of the avatar.
</ResponseField>

<ResponseField name="look_name" type="string">
  Name of the avatar look.
</ResponseField>

<ResponseField name="gender" type="string">
  Gender of the avatar: `male` or `female`.
</ResponseField>

<ResponseField name="age_range" type="string">
  Avatar age range.
</ResponseField>

<ResponseField name="ethnicity" type="string">
  Avatar ethnicity.
</ResponseField>

<ResponseField name="hair_color" type="string">
  Avatar hair color.
</ResponseField>

<ResponseField name="place" type="string">
  Place or context of the look (e.g., "studio", "office").
</ResponseField>

<ResponseField name="accessories" type="array">
  Visible accessories or props in the look.
</ResponseField>

<ResponseField name="action" type="string">
  Main action detected for the look.
</ResponseField>

<ResponseField name="emotion" type="string">
  Emotion or mood detected for the look.
</ResponseField>

<ResponseField name="selfie" type="boolean">
  Whether the look is a selfie-style shot.
</ResponseField>

<ResponseField name="format" type="string">
  Image format: `vertical` or `horizontal`.
</ResponseField>

<ResponseField name="thumbnail" type="string">
  URL of the look thumbnail image.
</ResponseField>

<ResponseField name="preview" type="string">
  Preview URL if available, otherwise `null`.
</ResponseField>

<ResponseField name="model_available" type="array">
  Array of available models for this look. If `preview` exists, only `standard` is available. Otherwise, models like `premium`, `ultra`, `veo-3-fast`, `veo-3-lite`, `omni-flash`, `ora-lite`, `ora-standard`, `ora-pro`, `seedance-2-fast`, `seedance-2-5`, and `seedance-2-5-1080p` may be available.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/avatar/list?gender=male&place=podcast&accessories=microphone" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/avatar/list"
  params = {"gender": "male", "place": "podcast", "accessories": "microphone"}
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/avatar/list');
  url.searchParams.set('gender', 'male');
  url.searchParams.set('place', 'podcast');
  url.searchParams.set('accessories', 'microphone');

  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  [
    {
      "id": "look_id",
      "avatar_id": "avatar_id_1",
      "avatar_name": "Avatar name",
      "look_name": "Look name",
      "gender": "male",
      "age_range": "adult",
      "ethnicity": "white-western-european",
      "hair_color": "brown",
      "place": "studio",
      "accessories": ["microphone"],
      "action": "presenting",
      "emotion": "focused",
      "selfie": false,
      "format": "vertical",
      "thumbnail": "https://cdn.example.com/thumbnail.jpg",
      "preview": null,
      "model_available": ["premium", "ultra", "veo-3-fast", "veo-3-lite", "omni-flash", "ora-lite", "ora-standard", "ora-pro", "seedance-2-fast", "seedance-2-5", "seedance-2-5-1080p"]
    },
    {
      "id": "look_id_2",
      "avatar_id": "avatar_id_1",
      "avatar_name": "Avatar name",
      "look_name": "Another Look",
      "gender": "female",
      "age_range": "young_adult",
      "ethnicity": "east-asian",
      "hair_color": "black",
      "place": "office",
      "accessories": ["laptop"],
      "action": "working",
      "emotion": "neutral",
      "selfie": false,
      "format": "horizontal",
      "thumbnail": "https://cdn.example.com/thumbnail2.jpg",
      "preview": "https://cdn.example.com/preview2.mp4",
      "model_available": ["standard"]
    }
  ]
  ```
</ResponseExample>

## Notes

* By default, looks from your space are returned first, followed by public catalog looks
* Set `onlyPublic=true` to return only public catalog looks (excludes custom space avatars)
* The `model_available` field indicates which video generation models can be used with this look
* If a look has a `preview` URL, it means the look is pre-rendered and only the `standard` model is available
* Use the `avatar_id` field when referencing the parent avatar, and the `id` field for the specific look when creating videos with the `/generation/start` endpoint


# Avatar Status
Source: https://docs.hoox.video/api-reference/avatars/status

GET https://app.hoox.video/api/public/v1/avatar/status
Check the generation status of a specific avatar look

## Overview

This endpoint allows you to check the generation status of a specific avatar look. Use this to monitor the progress of avatar creation or editing operations.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Query Parameters

<ParamField type="string">
  Unique identifier of the avatar.
</ParamField>

<ParamField type="string">
  Unique identifier of the look to check.
</ParamField>

## Response

<ResponseField name="avatar_id" type="string">
  Unique identifier of the avatar.
</ResponseField>

<ResponseField name="look_id" type="string">
  Unique identifier of the look.
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `pending`, `processing`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="result" type="object">
  Result object (only present when status is `completed`).

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier of the look.
    </ResponseField>

    <ResponseField name="avatar_name" type="string">
      Name of the avatar.
    </ResponseField>

    <ResponseField name="look_name" type="string">
      Name of the avatar look.
    </ResponseField>

    <ResponseField name="gender" type="string">
      Gender of the avatar (`male` or `female`).
    </ResponseField>

    <ResponseField name="place" type="string">
      Setting or location of the look.
    </ResponseField>

    <ResponseField name="accessories" type="array">
      Visible accessories or props in the look.
    </ResponseField>

    <ResponseField name="action" type="string">
      Main action detected for the look.
    </ResponseField>

    <ResponseField name="emotion" type="string">
      Emotion or mood detected for the look.
    </ResponseField>

    <ResponseField name="selfie" type="boolean">
      Whether the look is a selfie-style shot.
    </ResponseField>

    <ResponseField name="format" type="string">
      Format of the look (`vertical` or `horizontal`).
    </ResponseField>

    <ResponseField name="thumbnail" type="string">
      URL of the generated avatar look thumbnail.
    </ResponseField>

    <ResponseField name="model_available" type="array">
      List of available AI models for this look.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Error object (only present when status is `failed`).

  <Expandable title="properties">
    <ResponseField name="code" type="string">
      Error code.
    </ResponseField>

    <ResponseField name="message" type="string">
      Error message.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/avatar/status?avatar_id=avtr_123&look_id=look_abc" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/avatar/status"
  params = {"avatar_id": "avtr_123", "look_id": "look_abc"}
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/avatar/status');
  url.searchParams.set('avatar_id', 'avtr_123');
  url.searchParams.set('look_id', 'look_abc');

  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Pending theme={null}
  {
    "avatar_id": "avtr_123",
    "look_id": "look_abc",
    "status": "pending"
  }
  ```

  ```json Completed theme={null}
  {
    "avatar_id": "avtr_123",
    "look_id": "look_abc",
    "status": "completed",
    "result": {
      "id": "look_abc",
      "avatar_name": "Avatar name",
      "look_name": "Professional Office",
      "gender": "male",
      "place": "office",
      "accessories": ["laptop"],
      "action": "working",
      "emotion": "focused",
      "selfie": false,
      "format": "vertical",
      "thumbnail": "https://cdn.example.com/thumbnail.jpg",
      "model_available": ["premium", "ultra", "veo-3-fast", "veo-3-lite", "omni-flash", "ora-lite", "ora-standard", "ora-pro", "seedance-2-fast", "seedance-2-5", "seedance-2-5-1080p"]
    }
  }
  ```

  ```json Failed theme={null}
  {
    "avatar_id": "avtr_123",
    "look_id": "look_abc",
    "status": "failed",
    "error": {
      "code": "LOOK_GENERATION_FAILED",
      "message": "Generation failed"
    }
  }
  ```

  ```json Error 400 - Missing Parameters theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "MISSING_AVATAR_ID",
        "message": "avatar_id is required",
        "field": "avatar_id"
      }
    ]
  }
  ```

  ```json Error 404 - Look Not Found theme={null}
  {
    "error": "Look not found"
  }
  ```
</ResponseExample>

## Error Codes

* `INVALID_VALUE`: Missing required parameter (`avatar_id` or `look_id`)
* `Space not found`: The space associated with the API key doesn't exist
* `Avatar not found`: No avatar found with the specified `avatar_id`
* `Look not found`: No look found with the specified `look_id` for the avatar
* `LOOK_GENERATION_FAILED`: The look generation process failed (returned in status response when status is `failed`)


# Start Video Export
Source: https://docs.hoox.video/api-reference/export/start

POST https://app.hoox.video/api/public/v1/export/start
Export a generated video to downloadable MP4 format

## Overview

This endpoint exports a completed video to a downloadable MP4 file. Use this after your video generation is complete to get the final downloadable video file.

## Authentication

<Info>
  This endpoint requires API key authentication. Export costs may apply depending on how the video was created.
</Info>

## Request Body

<ParamField type="string">
  The video ID returned from completed video generation.
</ParamField>

<ParamField type="string">
  Export format override: `vertical` (9:16), `ads` (4:5), `square` (1:1), `horizontal` (16:9), or `custom`.
  If not specified, uses the original video format.
</ParamField>

<ParamField type="number">
  Custom video width in pixels (max 5000). Only used when format is `custom`. Defaults to 1080.
</ParamField>

<ParamField type="number">
  Custom video height in pixels (max 5000). Only used when format is `custom`. Defaults to 1920.
</ParamField>

<ParamField type="string">
  Avatar model quality: `standard`, `premium`, `ultra`, `veo-3-fast`, `veo-3-lite`, `omni-flash`, `ora-lite`, `ora-standard`, `ora-pro`, `seedance-2-fast`, `seedance-2-5`, or `seedance-2-5-1080p`. `seedance-2` and `seedance-2-1080p` are deprecated but still accepted.
  Available models for each avatar are returned in the `model_available` field when fetching avatars from the [avatar list endpoint](/api-reference/avatar/list).
  If not specified, the system automatically selects the best default model for your avatar (standard or premium).
</ParamField>

<ParamField type="string">
  URL to receive webhook notifications when export completes.
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  Unique identifier for the export job.
</ResponseField>

<ResponseField name="status" type="string">
  Current job status: `pending`.
</ResponseField>

<ResponseField name="estimated_credits" type="number">
  Estimated credit cost for this export (0 for API-generated videos).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/export/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "video_id": "vid_xyz789",
      "format": "vertical",
      "webhook_url": "https://your-app.com/webhooks/export"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/export/start"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "video_id": "vid_xyz789",
      "format": "vertical",
      "webhook_url": "https://your-app.com/webhooks/export"
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/export/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_id: "vid_xyz789",
      format: "vertical",
      webhook_url: "https://your-app.com/webhooks/export"
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "job_id": "export_abcd1234",
    "status": "pending",
    "estimated_credits": 0
  }
  ```

  ```json Error 400 - Missing Video ID theme={null}
  {
    "error": "video_id parameter is required",
    "code": "MISSING_VIDEO_ID"
  }
  ```

  ```json Error 404 - Video Not Found theme={null}
  {
    "error": "Video with specified ID doesn't exist",
    "code": "VIDEO_NOT_FOUND"
  }
  ```

  ```json Error 403 - Unauthorized Video theme={null}
  {
    "error": "Video doesn't belong to your space",
    "code": "UNAUTHORIZED_VIDEO"
  }
  ```
</ResponseExample>

## Export Formats

<CardGroup>
  <Card title="Vertical (9:16)" icon="mobile">
    **1080x1920**
    Perfect for TikTok, Instagram Stories, YouTube Shorts
  </Card>

  <Card title="Ads (4:5)" icon="rectangle-vertical">
    **1080x1350**
    Best for Instagram ads, Facebook ads, LinkedIn ads
  </Card>

  <Card title="Square (1:1)" icon="square">
    **1080x1080**
    Ideal for Instagram posts, Facebook, LinkedIn
  </Card>

  <Card title="Horizontal (16:9)" icon="rectangle-wide">
    **1920x1080**
    Perfect for YouTube, websites, presentations
  </Card>

  <Card title="Custom" icon="sliders">
    **Custom dimensions**
    Set your own width and height (max 5000px each)
  </Card>
</CardGroup>

## Credit Costs

Export costs depend on how the video was created, resolution, and which avatar model you choose:

### Base Export Cost

* **API-generated videos**: **0 credits** for base export (included in generation)
* **Dashboard-created videos**: 5 credits per 30 seconds

### High Resolution Cost

Additional charges apply for videos with resolution exceeding 1080p (width > 1920px OR height > 1080px):

* **High resolution surcharge**: **2.5 credits per 30 seconds** of video

<Warning>
  This surcharge applies to both API-generated and dashboard-created videos when exporting at high resolutions.
</Warning>

### Avatar Model Costs

Avatar costs apply only when your video includes an avatar. Cost calculation varies by model type:

<CardGroup>
  <Card title="Standard" icon="zap">
    **Free**

    Basic avatar quality with no additional cost.
  </Card>

  <Card title="Premium" icon="gem">
    **0.8 credits/sec**

    Highly realistic and dynamic avatars.
    Billed per second of **avatar visibility**.

    *Available from Start plan*
  </Card>

  <Card title="Ultra" icon="crown">
    **2.3 credits/sec**

    Enhanced realism with longer processing time.
    Billed per second of **avatar visibility**.

    *Enterprise plan only*
  </Card>

  <Card title="Veo 3 Fast" icon="bolt">
    **2.3 credits/sec**

    Google Veo 3 Fast model for quick generation.
    Billed per second of generated avatar segments.

    *Available from Start plan*
  </Card>

  <Card title="Veo 3 Lite" icon="zap">
    **1.2 credits/sec**

    Affordable Google Veo 3 model with good quality at lower cost.
    Billed per second of generated avatar segments.

    *Available from Start plan*
  </Card>

  <Card title="Omni Flash" icon="bolt">
    **3 credits/sec** (currently 50% off: 1.5 credits/sec)

    Google's latest model, sharper motion and lip sync.
    Billed per second of generated avatar segments.

    *Available from Start plan*
  </Card>

  <Card title="Ora Lite" icon="feather">
    **1 credit/sec**

    Fast and affordable avatar generation.
    Billed per second of generated avatar segments.

    *Enterprise plan only*
  </Card>

  <Card title="Ora Standard" icon="star">
    **2 credits/sec**

    High quality avatar in 1080p.
    Billed per second of generated avatar segments.

    *Enterprise plan only*
  </Card>

  <Card title="Ora Pro" icon="crown">
    **3 credits/sec**

    Higher expressivity and authentic movements.
    Billed per second of generated avatar segments.

    *Enterprise plan only*
  </Card>

  <Card title="Seedance 2 Fast" icon="bolt">
    **3 credits/sec**

    ByteDance Seedance 2 Fast model for quick avatar generation.
    Billed per second of generated avatar segments.

    *Available from Pro plan*
  </Card>

  <Card title="Seedance 2.5" icon="sparkles">
    **6 credits/sec**

    ByteDance Seedance 2.5 in 720p, longer single-shot takes up to 30s.
    Billed per second of generated avatar segments.

    *Available from Pro plan*
  </Card>

  <Card title="Seedance 2.5 1080p" icon="gem">
    **12 credits/sec**

    ByteDance Seedance 2.5 at the highest resolution.
    Billed per second of generated avatar segments.

    *Available from Pro plan*
  </Card>
</CardGroup>

<Warning>
  **Billing difference:** Premium and Ultra models bill based on avatar visibility duration, while Veo, Omni Flash, Ora and Seedance models bill based on avatar segments.
</Warning>

<Info>
  Deprecated models `seedance-2` (4 credits/sec) and `seedance-2-1080p` (6 credits/sec) are still accepted for existing integrations.
</Info>

<Info>
  All costs are calculated separately. Total cost = Base export cost + High resolution cost + Avatar cost.
</Info>

**Example 1**: A 60-second API video with 40 seconds of avatar visibility using the Premium model:

* Base export (API video): 0 credits
* Avatar cost: 40s × 0.8 = 32 credits (avatar visibility duration)
* **Total**: 32 credits

**Example 2**: A 60-second API video with 3 avatar segments using Veo 3 Fast:

* Base export (API video): 0 credits
* Avatar cost: 3 segments × 8 seconds × 2.3 = 55.2 credits
* **Total**: 55.2 credits

**Example 3**: A 60-second API video exported at 3840x2160 (4K):

* Base export (API video): 0 credits
* High resolution cost: 2 × 2.5 = 5 credits (60s = 2 segments of 30s)
* **Total**: 5 credits

**Example 4**: A 90-second dashboard video at 4K with 60 seconds of Premium avatar:

* Base export: 3 × 5 = 15 credits (90s = 3 segments of 30s)
* High resolution cost: 3 × 2.5 = 7.5 credits
* Avatar cost: 60s × 0.8 = 48 credits (avatar visibility)
* **Total**: 70.5 credits

## Prerequisites

Before exporting a video:

1. **Video must be completed**: Check generation status is `completed`
2. **Valid video\_id**: Use the `video_id` from generation result
3. **Video ownership**: Video must belong to your space

## Next Steps

After starting an export:

1. **Monitor Progress**: Use `/export/status/{jobId}` to check export progress
2. **Download Video**: Get the download URL when export completes
3. **Webhook Integration**: Set up webhooks for automatic notifications

## Error Codes

* `MISSING_VIDEO_ID`: video\_id parameter is required
* `VIDEO_NOT_FOUND`: Video with specified ID doesn't exist
* `UNAUTHORIZED_VIDEO`: Video doesn't belong to your space
* `VIDEO_NOT_READY`: Video generation must be completed first
* `INVALID_FORMAT`: Invalid export format specified
* `INVALID_AVATAR_MODEL`: Invalid avatar model specified
* `INCOMPATIBLE_AVATAR_MODEL`: Avatar model not compatible with this avatar
* `INVALID_PARAMETER`: avatar\_model cannot be used when video has no avatar
* `INSUFFICIENT_CREDITS`: Not enough credits for export (dashboard videos only)


# Check Export Status
Source: https://docs.hoox.video/api-reference/export/status

GET https://app.hoox.video/api/public/v1/export/status/{job_id}
Check the status of a video export job and get download URL

## Overview

This endpoint allows you to check the current status of a video export job. Use this to monitor export progress and retrieve the download URL when the export is complete.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Path Parameters

<ParamField type="string">
  The export job ID returned from the `/export/start` endpoint.
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  The unique identifier for the export job.
</ResponseField>

<ResponseField name="status" type="string">
  Current export status:

  * `pending`: Export is queued and waiting to start
  * `processing`: Export is in progress
  * `completed`: Export finished successfully
  * `failed`: Export failed
</ResponseField>

<ResponseField name="progress" type="number">
  Progress percentage (0-100).
</ResponseField>

<ResponseField name="current_step" type="string">
  Description of the current processing step.
</ResponseField>

<ResponseField name="result" type="object">
  Available when status is `completed`:

  <Expandable title="properties">
    <ResponseField name="video_url" type="string">
      Direct download URL for the exported MP4 file.
    </ResponseField>

    <ResponseField name="thumbnail_url" type="string">
      URL to the video thumbnail image.
    </ResponseField>

    <ResponseField name="cost" type="number">
      Actual credits consumed for export.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO timestamp when export completed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Available when status is `failed`:

  <Expandable title="properties">
    <ResponseField name="code" type="string">
      Error code describing the failure reason.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/export/status/export_abcd1234" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  job_id = "export_abcd1234"
  url = f"https://app.hoox.video/api/public/v1/export/status/{job_id}"
  headers = {
      "Authorization": "Bearer your_api_key"
  }

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

  # Download the video when ready
  if data.get('status') == 'completed':
      video_url = data['result']['video_url']
      video_response = requests.get(video_url)
      with open('video.mp4', 'wb') as f:
          f.write(video_response.content)
  ```

  ```javascript JavaScript theme={null}
  const jobId = "export_abcd1234";
  const response = await fetch(`https://app.hoox.video/api/public/v1/export/status/${job_id}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(data);

  // Download the video when ready
  if (data.status === 'completed') {
    const videoUrl = data.result.video_url;
    const videoResponse = await fetch(videoUrl);
    const blob = await videoResponse.blob();
    
    // Create download link
    const url = window.URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'video.mp4';
    a.click();
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Pending theme={null}
  {
    "job_id": "export_abcd1234",
    "status": "pending",
    "progress": 0,
    "current_step": "render"
  }
  ```

  ```json Processing theme={null}
  {
    "job_id": "export_abcd1234",
    "status": "processing",
    "progress": 65,
    "current_step": "render-audio"
  }
  ```

  ```json Completed theme={null}
  {
    "job_id": "export_abcd1234",
    "status": "completed",
    "progress": 100,
    "current_step": "render",
    "result": {
      "video_url": "https://storage.hoox.video/exports/export_abcd1234.mp4",
      "thumbnail_url": "https://storage.hoox.video/thumbnails/vid_xyz789.jpg",
      "cost": 0,
      "created_at": "2024-01-15T10:35:00Z"
    }
  }
  ```

  ```json Failed theme={null}
  {
    "job_id": "export_abcd1234",
    "status": "failed",
    "progress": 30,
    "current_step": "avatar",
    "error": {
      "code": "ENCODING_FAILED",
      "message": "Failed to encode video in the requested format"
    }
  }
  ```

  ```json Error 404 - Job Not Found theme={null}
  {
    "error": "Export job not found",
    "code": "JOB_NOT_FOUND"
  }
  ```

  ```json Error 403 - Unauthorized Job theme={null}
  {
    "error": "Export job does not belong to your space",
    "code": "UNAUTHORIZED_JOB"
  }
  ```
</ResponseExample>

## Polling Best Practices

<Tip>
  **Recommended polling strategy for exports:**

  1. Start with 3-second intervals (exports are typically faster than generation)
  2. Increase to 5-second intervals after 30 seconds
  3. Increase to 10-second intervals after 2 minutes
  4. Use webhooks for more efficient status updates
</Tip>

## Export Steps

During processing, you'll see various `current_step` values:

* **"render-audio"**: Processing audio in for the avatar export step
* **"avatar"**: Processing avatar generation
* **"render"**: Rendering the final video file

## Download URL Details

<Warning>
  **Important notes about download URLs:**

  * URLs are valid for 7  from completion
  * Download the file to your own storage for permanent access
</Warning>

## Error Codes

Common error codes you might encounter:

* `JOB_NOT_FOUND`: Export job ID doesn't exist
* `UNAUTHORIZED_JOB`: Export job doesn't belong to your space
* `EXPORT_FAILED`: General export failure
* `ENCODING_FAILED`: Video encoding failed
* `FORMAT_CONVERSION_FAILED`: Failed to convert video format
* `STORAGE_FAILED`: Failed to upload to storage


# Create Folder
Source: https://docs.hoox.video/api-reference/folders/create

POST https://app.hoox.video/api/public/v1/folder/create
Create an asset or video folder in your space to organize your library

## Overview

Creates a folder in your space to keep your library organized. A folder is scoped to a **type** — either `assets` (images/videos generated via [Submit Asset Generation](/api-reference/assets/start)) or `videos` (videos produced through the video workflow).

For asset folders, pass the returned `id` as `folder_id` when calling [Submit Asset Generation](/api-reference/assets/start) and the outputs land in that folder.

<Tip>
  When you start a batch of generations or work on a specific project, create a dedicated folder first and route every generation into it. It keeps the space tidy and makes the assets easy to find in the dashboard.
</Tip>

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField type="string">
  Display name of the folder.
</ParamField>

<ParamField type="string">
  Folder type: `assets` or `videos`. Determines which library the folder appears in.
</ParamField>

<ParamField type="string">
  ID of an existing folder **of the same type** to nest this one under. Omit (or pass `null`) to create a folder at the root of the library.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the created folder. For an asset folder, pass this as `folder_id` to [Submit Asset Generation](/api-reference/assets/start).
</ResponseField>

<ResponseField name="name" type="string">
  Name of the folder.
</ResponseField>

<ResponseField name="type" type="string">
  Folder type: `assets` or `videos`.
</ResponseField>

<ResponseField name="parent_folder_id" type="string">
  ID of the parent folder, or `null` for a root folder.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## Examples

<RequestExample>
  ```bash Asset folder theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/folder/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Summer Campaign",
      "type": "assets"
    }'
  ```

  ```bash Video folder theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/folder/create" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q3 Ads",
      "type": "videos"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/folder/create"
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.post(url, headers=headers, json={"name": "Summer Campaign", "type": "assets"})
  folder = response.json()

  # Route generations into the asset folder
  requests.post(
      "https://app.hoox.video/api/public/v1/asset/start",
      headers=headers,
      json={
          "type": "image",
          "model": "flux-2-pro",
          "prompt": "Product shot of a ceramic mug on a marble counter.",
          "folder_id": folder["id"],
      },
  )
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://app.hoox.video/api/public/v1/folder/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'Summer Campaign', type: 'assets' }),
  });

  const folder = await res.json();
  console.log(folder.id);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "662f8c1d3a4b5e6f70123456",
    "name": "Summer Campaign",
    "type": "assets",
    "parent_folder_id": null,
    "created_at": "2026-06-19T10:00:00.000Z"
  }
  ```

  ```json 400 Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      { "code": "missing_field", "message": "name is required", "field": "name" }
    ]
  }
  ```

  ```json 400 Invalid Parent theme={null}
  {
    "error": "folder_id does not reference an existing assets folder",
    "details": [
      { "code": "invalid_value", "message": "folder_id does not reference an existing assets folder" }
    ]
  }
  ```
</ResponseExample>

## Notes

* `type` defaults to `assets` when omitted.
* A `parent_folder_id` must reference a folder of the **same** `type`, otherwise the request fails with `invalid_value`.
* Use [List Folders](/api-reference/folders/list) to retrieve existing folder IDs before creating duplicates.


# List Folders
Source: https://docs.hoox.video/api-reference/folders/list

GET https://app.hoox.video/api/public/v1/folder/list
List the folders in your space, optionally filtered by type

## Overview

Returns the folders in your space. By default it returns **every** folder; pass `type` to return only asset folders or only video folders. Use a folder's `id` as `folder_id` when calling [Submit Asset Generation](/api-reference/assets/start), or check this list before creating a new folder to avoid duplicates.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Query Parameters

<ParamField type="string">
  Filter by folder type: `assets` or `videos`. Omit to return folders of all types.
</ParamField>

## Response

<ResponseField name="folders" type="array">
  Array of folder objects.

  <Expandable title="folder properties">
    <ResponseField name="id" type="string">
      Unique identifier of the folder. For an asset folder, pass this as `folder_id` to [Submit Asset Generation](/api-reference/assets/start).
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the folder.
    </ResponseField>

    <ResponseField name="type" type="string">
      Folder type: `assets` or `videos`.
    </ResponseField>

    <ResponseField name="parent_folder_id" type="string">
      ID of the parent folder, or `null` for a root folder.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<RequestExample>
  ```bash All folders theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/folder/list" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```bash Asset folders only theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/folder/list?type=assets" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/folder/list"
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.get(url, headers=headers, params={"type": "assets"})
  print(response.json()["folders"])
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/folder/list');
  url.searchParams.set('type', 'assets');

  const res = await fetch(url, {
    headers: { 'Authorization': 'Bearer your_api_key' },
  });

  const { folders } = await res.json();
  console.log(folders);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "folders": [
      {
        "id": "662f8c1d3a4b5e6f70123456",
        "name": "Summer Campaign",
        "type": "assets",
        "parent_folder_id": null,
        "created_at": "2026-06-19T10:00:00.000Z"
      },
      {
        "id": "662f8c1d3a4b5e6f70987654",
        "name": "Hero shots",
        "type": "assets",
        "parent_folder_id": "662f8c1d3a4b5e6f70123456",
        "created_at": "2026-06-19T10:05:00.000Z"
      }
    ]
  }
  ```
</ResponseExample>

## Notes

* Omitting `type` returns folders of every type; subfolders are identified by a non-null `parent_folder_id`.


# Start Video Generation
Source: https://docs.hoox.video/api-reference/generation/start

POST https://app.hoox.video/api/public/v1/generation/start
Start generating a video from a prompt, script, media files, or a ready-made editing plan

## Overview

This endpoint initiates video generation using various input methods. You can generate videos from text prompts, custom scripts, by providing your own media files (voice, avatar, images), or from a ready-made editing plan (`sequence_plan`) that controls the montage sequence by sequence.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField type="string">
  Text prompt describing the video content. Required if no script is provided.
</ParamField>

<ParamField type="number">
  Video duration in seconds (10-600). Required when using prompt.
</ParamField>

<ParamField type="string">
  Custom video script. Alternative to prompt-based generation.
</ParamField>

<ParamField type="string">
  ID of the voice to use. Get available voices from `/voice/list` endpoint.
</ParamField>

<ParamField type="string">
  URL to a custom voice file (audio format: mp3, wav, m4a).
</ParamField>

<ParamField type="string">
  ID of the avatar look to use. Get available avatars from `/avatar/list` endpoint.
</ParamField>

<ParamField type="string">
  URL to a custom avatar image/video file.
</ParamField>

<ParamField type="string">
  Video format: `vertical` (9:16), `square` (1:1), `ads` (4:5), `horizontal` (16:9), or `custom`.
</ParamField>

<ParamField type="number">
  Custom video width in pixels (max 5000). Only used when format is `custom`. Defaults to 1080.
</ParamField>

<ParamField type="number">
  Custom video height in pixels (max 5000). Only used when format is `custom`. Defaults to 1920.
</ParamField>

<ParamField type="array">
  Array of URLs to media files (images, videos) to include in the video.
</ParamField>

<ParamField type="array">
  Array of web URLs to extract content from (max 10).
</ParamField>

<ParamField type="object">
  <Expandable title="properties">
    <ParamField type="boolean">
      Enable web search for script generation.
    </ParamField>

    <ParamField type="boolean">
      Enable web search for relevant images.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="boolean">
  Whether to animate static images using AI.
</ParamField>

<ParamField type="number">
  Maximum number of images to animate.
</ParamField>

<ParamField type="boolean">
  Enable emotion enhancement for more expressive voices.
</ParamField>

<ParamField type="boolean">
  Use a native avatar model (audio and video generated together) for a higher quality avatar. (The video won't have audio before the export.)
</ParamField>

<ParamField type="string">
  Native avatar model used to pre-split the video timeline like the export will (e.g. `omni-flash`, `veo-3-fast`, `seedance-2-5`). Only used when `use_native_avatar` is enabled.
</ParamField>

<ParamField type="string">
  URL to receive webhook notifications when generation completes.
</ParamField>

<ParamField type="boolean">
  Whether to use media from your space library.
</ParamField>

<ParamField type="boolean">
  Whether to save generated media to your space library.
</ParamField>

<ParamField type="object">
  Enable or disable specific video features.

  <Expandable title="properties">
    <ParamField type="boolean">
      Enable adding automatic subtitles to the video.
    </ParamField>

    <ParamField type="boolean">
      Enable automatically placing background images/videos.
    </ParamField>

    <ParamField type="boolean">
      Enable adding automatic background music that matches the video style.
    </ParamField>

    <ParamField type="boolean">
      Enable adding automatic transitions.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  A ready-made editing plan: a flat array of speech blocks describing the montage sequence by sequence. When provided, it takes precedence over `prompt` and `script`. See the [Plan Content guide](/video-generation/overview#plan-content) for the concepts.

  <Expandable title="speech block properties">
    <ParamField type="array">
      Visual fragments of this speech block, in playback order.

      <Expandable title="sequence properties">
        <ParamField type="string | null">
          Text spoken during this visual fragment. Use `null` for a silent sequence (then `duration_ms` is required and the sequence must be alone in a dedicated silent block).
        </ParamField>

        <ParamField type="number">
          Fixed duration in milliseconds. Only for silent sequences (`text: null`) — spoken sequences are always timed from the generated audio.
        </ParamField>

        <ParamField type="string">
          Avatar look override for this sequence only. Defaults to the block's look, then to the request-level `avatar_id`.
        </ParamField>

        <ParamField type="string">
          What the avatar does while speaking this sequence, in plain language (e.g. `He frowns thoughtfully and touches his chin`). Applied at export by the avatar models that accept motion direction (the native models and `premium`).
        </ParamField>

        <ParamField type="object">
          Media displayed during this sequence. Omit it to let automatic B-roll fill the slot (only happens when no sequence of the whole plan carries a media).

          <Expandable title="media properties">
            <ParamField type="string">
              Media id from your space library. Takes precedence over `url`.
            </ParamField>

            <ParamField type="string">
              Public URL of an image or video to display.
            </ParamField>

            <ParamField type="string">
              How the media is displayed relative to the avatar: `full` (covers the whole frame), `half` (split with the avatar), `background` (behind the avatar on green screen), or `hide` (attached but not shown).
            </ParamField>

            <ParamField type="number">
              For videos: trim the source to start at this time (in seconds).
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField type="string">
      Voice for this whole block. Falls back to the request-level `voice_id`. Ignored for silent blocks.
    </ParamField>

    <ParamField type="string">
      Pre-recorded audio URL for this block — skips voice generation for it.
    </ParamField>

    <ParamField type="string">
      Parent avatar of this block. Falls back to the request-level `avatar_id`.
    </ParamField>

    <ParamField type="string">
      Default avatar look for this block's sequences.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  Unique identifier for the generation job.
</ResponseField>

<ResponseField name="status" type="string">
  Current job status: `pending`.
</ResponseField>

<ResponseField name="estimated_credits" type="number">
  Estimated credit cost for this generation.
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/generation/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create a video about sustainable energy solutions",
      "duration": 60,
      "voice_id": "voice_en_us_female_1",
      "avatar_id": "avatar_business_woman_1",
      "format": "vertical",
      "web_search": {
        "script": true,
        "images": true
      },
      "animate_image": true,
      "enable": {
        "subtitles": true,
        "broll": true,
        "music": true,
        "transitions": true
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/generation/start"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "prompt": "Create a video about sustainable energy solutions",
      "duration": 60,
      "voice_id": "voice_en_us_female_1",
      "avatar_id": "avatar_business_woman_1",
      "format": "vertical",
      "web_search": {
          "script": True,
          "images": True
      },
      "animate_image": True,
      "enable": {
          "subtitles": True,
          "broll": True,
          "music": True,
          "transitions": True
      }
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/generation/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Create a video about sustainable energy solutions",
      duration: 60,
      voice_id: "voice_en_us_female_1",
      avatar_id: "avatar_business_woman_1",
      format: "vertical",
      web_search: {
        script: true,
        images: true
      },
      animate_image: true,
      enable: {
        subtitles: true,
        broll: true,
        music: true,
        transitions: true
      }
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "job_id": "run_abcd1234",
    "status": "pending",
    "estimated_credits": 85
  }
  ```

  ```json Error 400 - Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "MISSING_FIELD",
        "message": "Duration is required when using prompt",
        "field": "duration"
      }
    ]
  }
  ```

  ```json Error 402 - Insufficient Credits theme={null}
  {
    "error": "Insufficient credits. Required: 85, Available: 45",
    "code": "INSUFFICIENT_CREDITS"
  }
  ```
</ResponseExample>

### Plan-based Example

This request generates a two-speaker video from a ready-made plan. The top-level `voice_id` and `avatar_id` are the defaults; the second block overrides them with a different voice and look, and one sequence swaps to a close-up look and directs the avatar with an `action`.

```bash cURL theme={null}
curl -X POST "https://app.hoox.video/api/public/v1/generation/start" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "voice_en_us_female_1",
    "avatar_id": "look_default",
    "format": "vertical",
    "sequence_plan": [
      {
        "sequences": [
          {
            "text": "We waste 3 hours a day.",
            "media": { "asset_id": "65f0a1b2c3d4e5f6a7b8c9d0", "show": "full" }
          },
          {
            "text": "Without even noticing.",
            "look_id": "look_closeup",
            "action": "He shakes his head slowly"
          }
        ]
      },
      {
        "sequences": [
          { "text": null, "duration_ms": 1200 }
        ]
      },
      {
        "voice_id": "voice_en_us_male_1",
        "look_id": "look_second_speaker",
        "sequences": [
          {
            "text": "Oh yeah? How come?",
            "media": { "url": "https://your-domain.com/chart.jpg", "show": "half" }
          }
        ]
      }
    ]
  }'
```

<Note>
  The silent pause (`{ "text": null, "duration_ms": 1200 }`) sits in its own block with no `voice_id` — that is required for every silent sequence.
</Note>

## Input Methods

### 1. Prompt-based Generation

Provide a `prompt` and `duration`. The AI will generate a script and find relevant media.

### 2. Script-based Generation

Provide a custom `script` along with `voice_id` or `voice_url`.

### 3. Media-based Generation

Provide `voice_url` and/or `avatar_url` with custom media files.

### 4. Plan-based Generation

Provide a `sequence_plan` — a flat array of speech blocks — describing the montage sequence by sequence. This takes precedence over `prompt` and `script`: the video is assembled exactly as planned. The request-level `voice_id` / `avatar_id` act as defaults for blocks and sequences that don't override them. See the [Plan Content guide](/video-generation/overview#plan-content) for the concepts.

## Credit Costs

Generation costs depend on several factors:

* **Base cost**: 5 credits every 30 seconds (with 15 seconds of buffer)
* **Image animation**: +5 credits per image

## Next Steps

1. **Monitor Progress**: Check status with `/generation/status/{job_id}`
2. **Export Video**: Use `/export/start` endpoint to export the video in the desired format
3. **Monitor Export Progress**: Check status with `/export/status/{job_id}`

## Error Codes

* `MISSING_CONTENT`: No prompt, script, voice\_url, or avatar\_url provided
* `MISSING_FIELD`: Required duration missing when using prompt
* `MISSING_VOICE`: No voice specified when using custom script
* `INSUFFICIENT_CREDITS`: Not enough credits available
* `INVALID_VOICE_ID`: Voice ID not found
* `INVALID_AVATAR_ID`: Avatar ID not found
* `INVALID_FORMAT`: Invalid video format
* `INVALID_PLAN`: The `sequence_plan` failed schema validation (the offending field is returned in `details`)
* `PLAN_RESOLUTION_FAILED`: A `voice_id`, `avatar_id`, or `look_id` referenced in the plan could not be found in your space


# Check Generation Status
Source: https://docs.hoox.video/api-reference/generation/status

GET https://app.hoox.video/api/public/v1/generation/status/{jobId}
Check the status of a video generation job

## Overview

This endpoint allows you to check the current status of a video generation job. Use this to monitor progress and retrieve the final video when generation is complete.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Path Parameters

<ParamField type="string">
  The job ID returned from the `/generation/start` endpoint.
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  The unique identifier for the generation job.
</ResponseField>

<ResponseField name="status" type="string">
  Current job status:

  * `pending`: Job is queued and waiting to start
  * `processing`: Generation is in progress
  * `completed`: Generation finished successfully
  * `failed`: Generation failed
</ResponseField>

<ResponseField name="progress_step" type="number">
  Progress percentage (0-100).
</ResponseField>

<ResponseField name="current_step" type="string">
  Description of the current processing step.
</ResponseField>

<ResponseField name="result" type="object">
  Available when status is `completed`:

  <Expandable title="properties">
    <ResponseField name="video_id" type="string">
      Unique identifier for the generated video.
    </ResponseField>

    <ResponseField name="duration" type="number">
      Actual video duration in seconds.
    </ResponseField>

    <ResponseField name="cost" type="number">
      Actual credits consumed for generation.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO timestamp when generation completed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  Available when status is `failed`:

  <Expandable title="properties">
    <ResponseField name="code" type="string">
      Error code describing the failure reason.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/generation/status/run_abcd1234" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  job_id = "run_abcd1234"
  url = f"https://app.hoox.video/api/public/v1/generation/status/{job_id}"
  headers = {
      "Authorization": "Bearer your_api_key"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const jobId = "run_abcd1234";
  const response = await fetch(`https://app.hoox.video/api/public/v1/generation/status/${job_id}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Pending theme={null}
  {
    "job_id": "run_abcd1234",
    "status": "pending",
    "progress_step": 0,
    "current_step": "QUEUE"
  }
  ```

  ```json Processing theme={null}
  {
    "job_id": "run_abcd1234",
    "status": "processing",
    "progress_step": 45,
    "current_step": "VOICE_GENERATION"
  }
  ```

  ```json Completed theme={null}
  {
    "job_id": "run_abcd1234",
    "status": "completed",
    "progress_step": 100,
    "current_step": "REDIRECTING",
    "result": {
      "video_id": "vid_xyz789",
      "duration": 62,
      "cost": 78,
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
  ```

  ```json Failed theme={null}
  {
    "job_id": "run_abcd1234",
    "status": "failed",
    "progress_step": 25,
    "current_step": "VOICE_GENERATION",
    "error": {
      "code": "VOICE_GENERATION_FAILED",
      "message": "Failed to generate voice audio from the provided script"
    }
  }
  ```

  ```json Error 404 - Job Not Found theme={null}
  {
    "error": "Job not found",
    "code": "JOB_NOT_FOUND"
  }
  ```

  ```json Error 403 - Unauthorized Job theme={null}
  {
    "error": "Job does not belong to your space",
    "code": "UNAUTHORIZED_JOB"
  }
  ```
</ResponseExample>

## Polling Best Practices

<Tip>
  **Recommended polling strategy:**

  1. Start with a 5-second interval for the first minute
  2. Increase to 10-second intervals after 1 minute
  3. Increase to 30-second intervals after 5 minutes
  4. Use webhooks for more efficient status updates
</Tip>

## Next Steps

Once your video generation is complete (`status: "completed"`):

1. Note the `video_id` from the result
2. Use the `/export/start` endpoint to export your video in the desired format
3. Monitor the export progress with `/export/status/{job_id}`

## Error Codes

Common error codes you might encounter:

* `JOB_NOT_FOUND`: Job ID doesn't exist
* `UNAUTHORIZED_JOB`: Job doesn't belong to your space
* `GENERATION_FAILED`: General generation failure
* `SCRIPT_GENERATION_FAILED`: Failed to generate script from prompt
* `VOICE_GENERATION_FAILED`: Voice processing failed
* `AVATAR_PROCESSING_FAILED`: Avatar preparation failed
* `MEDIA_PROCESSING_FAILED`: Media file processing failed
* `ASSEMBLY_FAILED`: Final video assembly failed


# Generate Script
Source: https://docs.hoox.video/api-reference/script/generate

POST https://app.hoox.video/api/public/v1/script/generate
Generate a video script from a prompt with cost estimation

## Overview

This endpoint generates a video script from a text prompt. It's useful for getting an accurate cost estimate before committing to full video generation, and for reviewing/editing the script before proceeding.

## Authentication

<Info>
  This endpoint requires API key authentication and consumes credits from your account.
</Info>

## Request Body

<ParamField type="string">
  Text prompt describing the video content (max 10,000 characters).
</ParamField>

<ParamField type="number">
  Target video duration in seconds (10-600).
</ParamField>

<ParamField type="array">
  Array of web URLs to extract content from (max 10).
</ParamField>

<ParamField type="boolean">
  Enable web search to find additional relevant content.
</ParamField>

## Response

<ResponseField name="script" type="string">
  The generated video script.
</ResponseField>

<ResponseField name="cost" type="number">
  Credits consumed for script generation.
</ResponseField>

<ResponseField name="extractedImages" type="array">
  Array of image URLs extracted from web sources (strings).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/script/generate" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create an educational video about renewable energy sources, focusing on solar and wind power",
      "duration": 90,
      "webSearch": true,
      "urls": ["https://www.energy.gov/renewable-energy"]
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/script/generate"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "prompt": "Create an educational video about renewable energy sources, focusing on solar and wind power",
      "duration": 90,
      "webSearch": True,
      "urls": ["https://www.energy.gov/renewable-energy"]
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/script/generate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Create an educational video about renewable energy sources, focusing on solar and wind power",
      duration: 90,
      webSearch: true,
      urls: ["https://www.energy.gov/renewable-energy"]
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "script": "In today's world, renewable energy has become more crucial than ever. Let's explore two of the most promising sources: solar and wind power.\n\nSolar energy harnesses the power of the sun through photovoltaic panels. These panels convert sunlight directly into electricity, providing a clean and abundant energy source. The technology has advanced significantly, making solar power more affordable and efficient than ever before.\n\nWind power, on the other hand, captures the kinetic energy of moving air through wind turbines. These towering structures can generate substantial amounts of electricity, especially in areas with consistent wind patterns.\n\nBoth technologies offer significant environmental benefits, reducing our dependence on fossil fuels and helping combat climate change. As we move forward, these renewable sources will play an increasingly important role in our energy future.",
    "cost": 15,
    "extractedImages": [
      "https://example.com/solar-panels.jpg",
      "https://example.com/wind-turbines.jpg",
      "https://example.com/renewable-energy-chart.png"
    ]
  }
  ```

  ```json Error 400 - Validation Failed theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "MISSING_FIELD",
        "message": "Prompt is required",
        "field": "prompt"
      }
    ]
  }
  ```

  ```json Error 402 - Insufficient Credits theme={null}
  {
    "error": "Insufficient credits. Required: 15, Available: 8",
    "code": "INSUFFICIENT_CREDITS"
  }
  ```
</ResponseExample>

## Credit Costs

Script generation costs are based on:

* **Base cost**: 0.1 credits every 60 seconds
* **Web search**: +0.1 credits when enabled
* **URL processing**: +0.1 credits per URL

<Tip>
  Script generation costs are separate from video generation costs.
</Tip>

## Usage Tips

### 1. Content Enhancement

* Use `webSearch: true` to find relevant, up-to-date information
* Provide specific URLs to extract content from predefined pages (like product page or article)
* Review extracted images to see what visual content was found

### 2. Script Customization

* Edit the generated script before using it in video generation
* Adjust prompt to match your brand voice and pacing
* Add specific product mentions or calls-to-action

## Error Codes

* `MISSING_FIELD`: Prompt is required
* `INVALID_TYPE`: Invalid parameter type
* `INVALID_VALUE`: Parameter value out of allowed range
* `INSUFFICIENT_CREDITS`: Not enough credits for script generation
* `SCRIPT_GENERATION_FAILED`: Failed to generate script

## Next Steps

After generating a script:

1. **Review and Edit**: Modify the script to match your needs
2. **Choose Resources**: Use `/voice/list` and `/avatar/list` to select voice and avatar
3. **Generate Video**: Use the script in `/generation/start` endpoint
4. **Monitor Progress**: Check status with `/generation/status/{job_id}`
5. **Export Video**: Use `/export/start` endpoint to export the video in the desired format
6. **Monitor Export Progress**: Check status with `/export/status/{job_id}`


# Duplicate Video
Source: https://docs.hoox.video/api-reference/video/duplicate

POST https://app.hoox.video/api/public/v1/video/duplicate
Duplicate an existing completed video, optionally with a new voice and/or avatar look

## Overview

This endpoint duplicates an existing completed video inside the same space.

* If **no optional parameters** are provided, it creates an exact copy of the video.
* You can **optionally apply** a new voice and/or a new avatar look to the duplicated video while keeping the original script, structure, and media.

The original video must belong to your space and be in `done` status.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Request Body

<ParamField type="string">
  Unique identifier of the original video to duplicate.\
  The video must belong to your space and be in `done` status (completed generation).
</ParamField>

<ParamField type="string">
  Optional ID of the avatar look to apply on the duplicated video.\
  Use an ID returned by the [avatar resources endpoint](/api-reference/resources/avatars) or from your custom avatars.\
  When provided, the duplicated video will reference this new look, and avatar renders will be regenerated as needed.
</ParamField>

<ParamField type="string">
  Optional ID of the voice to use for the duplicated video.\
  Use an ID returned by the [voice resources endpoint](/api-reference/resources/voices) or from your custom voices.\
  For standard videos, the endpoint regenerates the audio and subtitles with the new voice.\
  For native avatar videos (generated with `use_native_avatar`), audio is generated later during export.
</ParamField>

## Response

<ResponseField name="video_id" type="string">
  Unique identifier of the newly duplicated video.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the duplicated video.\
  Typically `done`, meaning the video is ready to be exported.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message describing the result of the duplication.
</ResponseField>

<ResponseField name="changes_applied" type="object">
  Details of which changes were applied to the duplicated video.

  <Expandable title="properties">
    <ResponseField name="voice_changed" type="boolean">
      `true` if a new voice was applied using `voice_id`.
    </ResponseField>

    <ResponseField name="avatar_changed" type="boolean">
      `true` if a new avatar look was applied using `avatar_look_id`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/video/duplicate" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "video_id": "vid_abc123",
      "voice_id": "voice_en_us_female_1",
      "avatar_look_id": "avatar_business_woman_office_1"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/video/duplicate"
  headers = {
      "Authorization": "Bearer your_api_key",
      "Content-Type": "application/json"
  }

  data = {
      "video_id": "vid_abc123",
      "voice_id": "voice_en_us_female_1",
      "avatar_look_id": "avatar_business_woman_office_1"
  }

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/video/duplicate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_id: "vid_abc123",
      voice_id: "voice_en_us_female_1",
      avatar_look_id: "avatar_business_woman_office_1"
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "video_id": "vid_dup_456",
    "status": "done",
    "message": "Video duplicated successfully. The video will need to be exported to generate the final output.",
    "changes_applied": {
      "voice_changed": true,
      "avatar_changed": true
    }
  }
  ```

  ```json Error 400 - Missing Video ID theme={null}
  {
    "error": "Validation failed",
    "details": [
      {
        "code": "MISSING_VIDEO_ID",
        "message": "video_id is required",
        "field": "video_id"
      }
    ]
  }
  ```

  ```json Error 404 - Video Not Found theme={null}
  {
    "error": "Video not found",
    "details": [
      {
        "code": "VIDEO_NOT_FOUND",
        "message": "Video with ID \"vid_abc123\" not found"
      }
    ]
  }
  ```

  ```json Error 403 - Unauthorized Video theme={null}
  {
    "error": "Unauthorized",
    "details": [
      {
        "code": "UNAUTHORIZED_VIDEO",
        "message": "This video does not belong to your space"
      }
    ]
  }
  ```

  ```json Error 400 - Video Not Ready theme={null}
  {
    "error": "Video not ready",
    "details": [
      {
        "code": "VIDEO_NOT_READY",
        "message": "Only completed videos can be duplicated"
      }
    ]
  }
  ```
</ResponseExample>

## Prerequisites

Before duplicating a video:

1. **Completed video**: The original video must be in `done` status.
2. **Video ownership**: The video must belong to your space.
3. **Valid video\_id**: Provide the ID of an existing video in your space.

## Error Codes

* `MISSING_VIDEO_ID`: `video_id` parameter is required.
* `INVALID_TYPE`: One of the parameters has an invalid type (must be strings).
* `INVALID_VOICE_ID`: Provided `voice_id` does not match any available voice.
* `INVALID_AVATAR_ID`: Provided `avatar_look_id` does not match any available avatar look.
* `VIDEO_NOT_FOUND`: Video with specified ID does not exist.
* `UNAUTHORIZED_VIDEO`: Video does not belong to your space.
* `VIDEO_NOT_READY`: Video must be completed before duplication.
* `INTERNAL_ERROR`: Unexpected internal server error.


# Get Voice
Source: https://docs.hoox.video/api-reference/voices/get

GET https://app.hoox.video/api/public/v1/voice/{id}
Retrieve details of a specific voice by its ID

## Overview

This endpoint retrieves details for a specific voice by its `id`. Results can come from your space (custom voices) or from the public catalog filtered by your plan.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Path Parameters

<ParamField type="string">
  The identifier of the voice to retrieve.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier of the voice.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the voice.
</ResponseField>

<ResponseField name="language" type="string">
  Language code of the voice (e.g., `fr`, `en`).
</ResponseField>

<ResponseField name="gender" type="string">
  Gender of the voice: `male` or `female`.
</ResponseField>

<ResponseField name="tags" type="array">
  Array of tags associated with the voice (e.g., `[\"friendly\", \"warm\"]`).
</ResponseField>

<ResponseField name="source" type="string">
  Source of the voice: `space` (custom voice) or `config` (public catalog).
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/voice/voice_fr_female_01" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/voice/voice_fr_female_01"
  headers = {"Authorization": "Bearer your_api_key"}
  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/voice/voice_fr_female_01', {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "voice_fr_female_01",
    "name": "Charlotte",
    "language": "fr",
    "gender": "female",
    "tags": ["friendly", "warm"],
    "source": "config"
  }
  ```

  ```json Error 404 - Not Found theme={null}
  {
    "error": "Voice not found",
    "details": [
      {
        "code": "NOT_FOUND",
        "message": "Voice with id \"voice_fr_female_01\" not found"
      }
    ]
  }
  ```
</ResponseExample>


# List Voices
Source: https://docs.hoox.video/api-reference/voices/list

GET https://app.hoox.video/api/public/v1/voice/list
Retrieve available voices for your space, filtered by plan and optional filters

## Overview

This endpoint retrieves a list of available voices. It returns your custom space voices first (if any), followed by voices from the public catalog filtered according to your plan. Results can be filtered by language, gender, and tags.

## Authentication

<Info>
  This endpoint requires API key authentication. Include your API key in the `Authorization` header.
</Info>

## Query Parameters

<ParamField type="string">
  Filter by language code (e.g., `fr`, `en`, `es`).
</ParamField>

<ParamField type="string">
  Filter by gender: `male` or `female`.
</ParamField>

<ParamField type="string">
  Filter by tags. Provide a comma-separated list (e.g., `friendly,warm`).
</ParamField>

<ParamField type="boolean">
  If `true`, returns only public catalog voices (excludes custom space voices). Defaults to `false` (returns both space and public voices).
</ParamField>

## Response

Returns an array of voice objects.

<ResponseField name="id" type="string">
  Unique identifier of the voice. Use this as `voice_id` in video generation.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the voice.
</ResponseField>

<ResponseField name="language" type="string">
  Language code of the voice (e.g., `fr`, `en`, `es`).
</ResponseField>

<ResponseField name="gender" type="string">
  Gender of the voice: `male` or `female`.
</ResponseField>

<ResponseField name="tags" type="array">
  Array of tags associated with the voice (e.g., `["friendly", "warm"]`).
</ResponseField>

<ResponseField name="source" type="string">
  Source of the voice: `space` (custom voice) or `config` (public catalog).
</ResponseField>

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/voice/list?language=fr&gender=female&tags=friendly,warm" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://app.hoox.video/api/public/v1/voice/list"
  params = {"language": "fr", "gender": "female", "tags": "friendly,warm"}
  headers = {"Authorization": "Bearer your_api_key"}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://app.hoox.video/api/public/v1/voice/list');
  url.searchParams.set('language', 'fr');
  url.searchParams.set('gender', 'female');
  url.searchParams.set('tags', 'friendly,warm');

  const response = await fetch(url, {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  [
    {
      "id": "voice_id",
      "name": "Charlotte",
      "language": "fr",
      "gender": "female",
      "tags": ["friendly", "warm"],
      "source": "config"
    },
    {
      "id": "custom_voice_123",
      "name": "My Custom Voice",
      "language": "fr",
      "gender": "male",
      "tags": ["professional"],
      "source": "space"
    }
  ]
  ```
</ResponseExample>

## Notes

* By default, custom voices from your space are returned first, followed by public catalog voices
* Set `onlyPublic=true` to return only public catalog voices (excludes custom space voices)
* Available voices depend on your plan:
  * **Free**: Only free tier voices
  * **Start**: Free + Start tier voices
  * **Pro**: Free + Start + Pro tier voices
  * **Enterprise**: All voices
* Use the `id` field as `voice_id` when creating videos with the `/generation/start` endpoint
* The `source` field helps distinguish between your custom voices and public catalog voices


# Authentication
Source: https://docs.hoox.video/authentication

How to authenticate your requests with the Hoox API

## Overview

The Hoox API uses API keys to authenticate requests. Your API key must be included in the `Authorization` header of all your requests.

## API Key Format

Hoox API keys follow this format:

* **Production**: `hx_live_` followed by 64 hexadecimal characters

Example: `hx_live_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef`

## Generating an API Key

<Steps>
  <Step title="Access settings">
    Log in to your [Hoox dashboard](https://app.hoox.video) and go to **Your Space** > **Settings** > **API**.
  </Step>

  <Step title="Check your plan">
    Make sure you have at least a **Pro** plan. API access is available from the Pro plan onward.
  </Step>

  <Step title="Generate the key">
    Click **Generate API Key** and give it a descriptive name.
  </Step>

  <Step title="Save the key">
    **Important**: Copy and save your key immediately. It will never be displayed again.
  </Step>
</Steps>

## Using the API Key

### Authentication Header

All requests must include the `Authorization` header:

```http theme={null}
Authorization: Bearer hx_live_your_api_key_here
```

### Implementation Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/voice/list" \
    -H "Authorization: Bearer hx_live_your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const headers = {
    'Authorization': 'Bearer hx_live_your_api_key_here',
    'Content-Type': 'application/json'
  };

  const response = await fetch('https://app.hoox.video/api/public/v1/voice/list', {
    headers
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://app.hoox.video/api/public/v1/voice/list', headers=headers)
  ```

  ```php PHP theme={null}
  $headers = [
      'Authorization: Bearer hx_live_your_api_key_here',
      'Content-Type: application/json'
  ];

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, 'https://app.hoox.video/api/public/v1/voice/list');
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  curl_close($ch);
  ```
</CodeGroup>

## API Key Management

### Revoking a Key

If your key is compromised:

1. Go to **Settings** > **API**
2. Click **Revoke** next to your key
3. Generate a new key immediately
4. Update your applications with the new key

### Regeneration

To renew your key:

1. Click **Regenerate** in the API settings
2. The old key will be immediately revoked
3. Save the new key
4. Update your applications

<Warning>
  Regeneration immediately revokes the old key. Make sure to update all your applications.
</Warning>

## Security

### Best Practices

<AccordionGroup>
  <Accordion title="Secure Storage">
    * Store your keys in environment variables
    * Never commit keys to source code
    * Use secret managers in production
  </Accordion>

  <Accordion title="Key Rotation">
    * Regenerate your keys regularly (every 3-6 months)
    * Monitor your key usage
    * Immediately revoke compromised keys
  </Accordion>

  <Accordion title="Access Restriction">
    * Limit API key access to necessary personnel only
    * Use different keys for different environments
    * Monitor usage logs
  </Accordion>
</AccordionGroup>

### Environment Variables

<CodeGroup>
  ```bash .env theme={null}
  HOOX_API_KEY=hx_live_your_api_key_here
  HOOX_API_URL=https://app.hoox.video/api/public/v1
  ```

  ```javascript Node.js theme={null}
  // Configuration
  const HOOX_API_KEY = process.env.HOOX_API_KEY;
  const HOOX_API_URL = process.env.HOOX_API_URL || 'https://app.hoox.video/api/public/v1';

  if (!HOOX_API_KEY) {
    throw new Error('HOOX_API_KEY environment variable is required');
  }

  // Usage
  const response = await fetch(`${HOOX_API_URL}/voice/list`, {
    headers: {
      'Authorization': `Bearer ${HOOX_API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  ```

  ```python Python theme={null}
  import os
  import requests

  # Configuration
  HOOX_API_KEY = os.getenv('HOOX_API_KEY')
  HOOX_API_URL = os.getenv('HOOX_API_URL', 'https://app.hoox.video/api/public/v1')

  if not HOOX_API_KEY:
      raise ValueError('HOOX_API_KEY environment variable is required')

  # Usage
  headers = {
      'Authorization': f'Bearer {HOOX_API_KEY}',
      'Content-Type': 'application/json'
  }

  response = requests.get(f'{HOOX_API_URL}/voice/list', headers=headers)
  ```
</CodeGroup>

## Authentication Errors

### Common Error Codes

| Code | Status | Description |
| - | - | - |
| `invalid_api_key` | 401 | Invalid or missing API key |
| `plan_required` | 403 | Pro plan required |
| `rate_limit_exceeded` | 429 | Rate limit exceeded |

### Error Response Example

```json theme={null}
{
  "error": "Invalid API key",
  "details": [
    {
      "code": "invalid_api_key",
      "message": "The provided API key is invalid or has been revoked"
    }
  ]
}
```

## Rate Limiting

Each API key has rate limits:

* **100 requests per minute** for Pro and Enterprise plans
* Limits are applied per workspace
* Response headers indicate your current usage

### Rate Limiting Headers

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

<Tip>
  Monitor the `X-RateLimit-*` headers to avoid exceeding your limits.
</Tip>


# Avatars
Source: https://docs.hoox.video/avatars/overview

Create, edit and track avatar generations with the Hoox API

## Avatar Workflow

Create avatars from a text prompt or from existing images, then generate additional looks by editing. You can receive webhooks on completion or poll a status endpoint.

<CardGroup>
  <Card title="From Prompt" icon="sparkles">
    Create a brand new avatar using a text prompt and a visual style.
  </Card>

  <Card title="From Images" icon="images">
    Build an avatar instantly from your own reference images. No generation cost.
  </Card>

  <Card title="Edit Look" icon="wand-magic">
    Generate a new look from an existing one using a prompt and optional extra images.
  </Card>

  <Card title="Status & Webhooks" icon="bell">
    Track generation status via polling or receive webhooks on completion/failure.
  </Card>
</CardGroup>

## Endpoints

### Create from Prompt

POST `/api/public/v1/avatar/create`

Request body:

```json theme={null}
{
  "prompt": "Young entrepreneur in a modern office, confident smile",
  "style": "iphone",
  "format": "vertical",
  "name": "Alex",
  "place": "office",
  "resolution": "2K",
  "elementImages": [
    "https://your-domain.com/logo.png"
  ],
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
```

Response:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_123"
}
```

<Info>
  Creation costs 2 credits for 2K resolution and 4 credits for 4K. Status starts as `pending` and becomes `ready` or `error`.
</Info>

### Create from Images

POST `/api/public/v1/avatar/create`

Request body:

```json theme={null}
{
  "imageUrls": [
    "https://your-domain.com/img1.jpg",
    "https://your-domain.com/img2.jpg"
  ],
  "name": "Jordan",
  "place": "studio",
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
```

Response:

```json theme={null}
{
  "avatar_id": "avtr_xyz",
  "look_id": "look_a"
}
```

<Info>
  No generation cost; looks are created instantly with status `ready`.
</Info>

### Edit an Avatar Look

POST `/api/public/v1/avatar/edit`

Request body:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_123",
  "prompt": "Same person, podcast scene, warm cinematic lighting",
  "style": "podcast",
  "format": "vertical",
  "resolution": "2K",
  "images": [
    "https://your-domain.com/extra-reference.jpg"
  ],
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
```

Response:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_edit_789"
}
```

<Info>
  Editing costs 2 credits for 2K resolution and 4 credits for 4K per new look. A new look is created in `pending` status and updated to `ready` or `error`.
</Info>

## Status & Webhooks

### Poll Generation Status

GET `/api/public/v1/avatar/status?avatar_id={avatarId}&look_id={lookId}`

Example response:

```json theme={null}
{
  "avatar_id": "avtr_abc",
  "look_id": "look_edit_789",
  "status": "completed",
  "result": {
    "thumbnail_url": "https://media.hoox.video/…/image.jpg"
  }
}
```

### Webhook Payloads

On success:

```json theme={null}
{
  "job_id": "look_edit_789",
  "status": "completed",
  "result": { "thumbnail_url": "https://media.hoox.video/.../image.jpg" }
}
```

On failure:

```json theme={null}
{
  "job_id": "look_edit_789",
  "status": "failed",
  "error": { "code": "GENERATION_FAILED", "message": "Edit failed" }
}
```

<Info>
  Provide a `webhook_url` in the request body to receive asynchronous updates. Otherwise, use the status endpoint to poll.
</Info>

## Next Steps

<CardGroup>
  <Card title="API Reference" icon="code" href="/api-reference/avatar/list">
    Detailed endpoints for avatar creation and editing
  </Card>

  <Card title="Video Generation Overview" icon="film" href="/video-generation/overview">
    Generate videos using your avatars
  </Card>
</CardGroup>


# Pricing & Credits
Source: https://docs.hoox.video/costs

Understand API pricing, credit consumption, and cost optimization

## Overview

Hoox API uses a credit-based pricing system where you pay for what you use. Credits are consumed when generating videos, creating scripts, and performing other operations. This guide explains how credits work and how to optimize your costs.

## Credit System

### How Credits Work

<Card title="Pay-per-Use Model" icon="credit-card">
  Credits are consumed only when operations are performed:

  * **Video Generation**: Based on duration and features
  * **Script Generation**: Fixed cost per generation
  * **Export**: Included for API videos, charged for dashboard videos
</Card>

## Video Generation Costs

Video generation costs depend on several factors:

### Base Costs

<CardGroup>
  <Card title="Standard Video" icon="play">
    **5 credits** every 30 seconds

    * Text-to-speech generation
    * Basic video assembly
    * Standard quality output
    * 15 seconds buffer included
  </Card>

  <Card title="With Animation" icon="sparkles">
    **+5 credits per image**

    * AI-powered movement
    * Cinematic effects
    * Professional quality
  </Card>
</CardGroup>

### Detailed Cost Breakdown

| Feature | Cost | Notes |
| - | - | - |
| **Base Generation** | 5 credits | Every 30 seconds (with 15s buffer) |
| **Image Animation** | +5 credits/image | Transform static images into videos |
| **Avatar Generation (2K)** | 2 credits | Create or edit an avatar in 2K |
| **Avatar Generation (4K)** | 4 credits | Create or edit an avatar in 4K |
| **Custom Media Processing** | Included | URL-based media integration |

### Cost Examples

<Tabs>
  <Tab title="Basic Video">
    **Simple 60-second video**

    ```
    Base cost (60s): 10 credits
    (5 credits per 30s x 2 tranches)
    Total: 10 credits
    ```
  </Tab>

  <Tab title="Premium Content">
    **60-second video with avatar + 3 animated images**

    ```
    Base cost (60s): 10 credits
    Image animation (3 × 5): +15 credits
    Total: 25 credits
    ```
  </Tab>
</Tabs>

## Script Generation Costs

Script generation has a separate, predictable cost structure:

| Feature | Cost | Notes |
| - | - | - |
| **Base Generation** | 0.1 credits per 60 seconds | AI-generated script |
| **Web Search** | +0.1 credits | Enhanced with real-time information |
| **URL Processing** | +0.1 credits per URL | Content extraction from provided URLs |

### Script Cost Examples

```python theme={null}
# Basic script generation
{
    "prompt": "Create a video about renewable energy",
    "duration": 60
}
# Cost: 0.1 credits (1 x 60s tranche)

# Enhanced script with web search
{
    "prompt": "Create a video about renewable energy",
    "duration": 60,
    "webSearch": True,
    "urls": ["https://energy.gov/renewable"]
}
# Cost: 0.3 credits (0.1 base + 0.1 web search + 0.1 per URL)
```

## Export Costs

Export costs vary based on how the video was created, resolution, and avatar model:

### Base Export Cost

<CardGroup>
  <Card title="API Videos" icon="code">
    **Included Free**

    First export is included in generation cost
  </Card>

  <Card title="Dashboard Videos" icon="browser">
    **5 credits per 30s**

    Standard export cost for dashboard-created videos
  </Card>
</CardGroup>

### High Resolution Surcharge

Videos exported at resolutions exceeding 1080p (width > 1920px OR height > 1080px) incur an additional cost:

<Card title="4K & Higher" icon="expand">
  **+2.5 credits per 30s**

  * Applies to custom formats above 1080p
  * Added to base export cost
  * Charged for all video types (API and dashboard)
</Card>

### Avatar Quality Models

When your video includes an avatar, you can choose from multiple quality models with different performance and cost characteristics:

<CardGroup>
  <Card title="Standard" icon="zap">
    **Free**

    Basic avatar quality that works well for most use cases. No additional credits required.

    **Best for:**

    * Quick exports
    * Budget-conscious projects
    * Testing and prototyping
  </Card>

  <Card title="Premium" icon="gem">
    **0.8 credits/sec** (avatar visibility)

    Highly realistic and dynamic avatar rendering with enhanced facial expressions and movements.

    **Best for:**

    * Professional content
    * Marketing videos
    * High-quality presentations

    *Available from Start plan*
  </Card>

  <Card title="Ultra" icon="crown">
    **2.3 credits/sec** (avatar visibility)

    Enhanced realism with the highest quality output. Longer processing time for superior results.

    **Best for:**

    * Premium content
    * Flagship campaigns
    * Maximum quality requirements

    *Enterprise plan only*
  </Card>

  <Card title="Veo 3 Fast" icon="google">
    **2.3 credits/sec** (per segment)

    Google Veo 3 Fast model for quick, high-quality generation with AI-powered avatars.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * Fast turnaround
    * AI-generated avatars
    * Modern content creation

    *Available from Start plan*
  </Card>

  <Card title="Veo 3" icon="google">
    **5 credits/sec** (per segment)

    Google Veo 3 standard model for the highest quality AI-generated avatars. Exceptional realism.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * Cutting-edge quality
    * Premium AI content
    * Maximum realism

    *Available from Start plan*
  </Card>

  <Card title="Veo 3 Lite" icon="google">
    **0.5 credits/sec** (720p) · **0.8 credits/sec** (1080p)

    Affordable Google Veo 3 model with good quality at lower cost. 720p for 4s/6s segments, 1080p for 8s segments.

    **Best for:**

    * Cost-effective content
    * High-volume production
    * Good quality at lower price

    *Available from Start plan*
  </Card>

  <Card title="Seedance 2" icon="sparkles">
    **4 credits/sec** (per segment)

    ByteDance Seedance 2 model for high-quality avatar generation with excellent realism.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * High-quality content
    * Realistic avatar rendering
    * Premium productions

    *Available from Pro plan*
  </Card>

  <Card title="Seedance 2 Fast" icon="bolt">
    **3 credits/sec** (per segment)

    ByteDance Seedance 2 Fast model for quick avatar generation with great quality.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * Fast turnaround
    * Good quality at speed
    * High-volume production

    *Available from Pro plan*
  </Card>
</CardGroup>

<Note>
  **Model availability:** Not all avatars support all models. Check the `model_available` field when fetching avatars to see which models are supported.
</Note>

<Info>
  Total export cost = Base cost + High resolution cost + Avatar cost
</Info>

### Export Cost Examples

<Tabs>
  <Tab title="Basic API Video">
    **60-second API video, standard resolution**

    ```
    Base export: 0 credits (included)
    High-res cost: 0 credits (≤1080p)
    Avatar cost: 0 credits (no avatar)
    Total: 0 credits
    ```
  </Tab>

  <Tab title="4K Export">
    **60-second API video at 3840x2160**

    ```
    Base export: 0 credits (included)
    High-res cost: 5 credits (2 × 2.5)
    Avatar cost: 0 credits (no avatar)
    Total: 5 credits
    ```
  </Tab>

  <Tab title="Premium with Avatar">
    **90-second dashboard video, 4K, 60s Premium avatar**

    ```
    Base export: 15 credits (3 × 5)
    High-res cost: 7.5 credits (3 × 2.5)
    Avatar cost: 48 credits (60s × 0.8)
    Total: 70.5 credits
    ```
  </Tab>

  <Tab title="API Video with Veo">
    **60-second API video with 3 Veo 3 Fast segments**

    ```
    Base export: 0 credits (included)
    High-res cost: 0 credits (≤1080p)
    Avatar cost: 55.2 credits (3 × 8s × 2.3)
    Total: 55.2 credits
    ```
  </Tab>
</Tabs>

### Recommended First Steps

1. **Test with simple content**: Start with basic videos to understand quality
2. **Experiment with features**: Try avatars and animations with small tests
3. **Monitor usage**: Track credit consumption patterns
4. **Scale gradually**: Increase feature usage based on results

## Next Steps

<CardGroup>
  <Card title="Get API Key" href="/authentication" icon="key">
    Start with free credits and test the platform
  </Card>

  <Card title="Quick Start Guide" href="/quickstart" icon="rocket">
    Create your first video and understand costs
  </Card>
</CardGroup>


# Error Handling
Source: https://docs.hoox.video/errors

Understanding and handling API errors

## Error Response Format

All API errors follow a consistent format:

```json theme={null}
{
  "error": "Brief error description",
  "details": [
    {
      "code": "specific_error_code",
      "message": "Detailed error message",
      "field": "field_name" // Optional, for validation errors
    }
  ]
}
```

## HTTP Status Codes

| Status Code | Description |
| - | - |
| `200` | Success |
| `201` | Created successfully |
| `400` | Bad Request - Invalid parameters |
| `401` | Unauthorized - Invalid or missing API key |
| `402` | Payment Required - Insufficient credits |
| `403` | Forbidden - Pro plan required or unauthorized access |
| `404` | Not Found - Resource doesn't exist |
| `409` | Conflict - Resource already exists |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Internal Server Error |

## Common Error Codes

### Authentication Errors

<AccordionGroup>
  <Accordion title="invalid_api_key">
    **Status**: 401\
    **Cause**: API key is invalid, expired, or malformed\
    **Solution**: Check your API key format and regenerate if necessary
  </Accordion>

  <Accordion title="plan_required">
    **Status**: 403\
    **Cause**: Pro plan required for API access\
    **Solution**: Upgrade to Pro plan
  </Accordion>
</AccordionGroup>

### Rate Limiting Errors

<AccordionGroup>
  <Accordion title="rate_limit_exceeded">
    **Status**: 429\
    **Cause**: Too many requests in a short period\
    **Solution**: Implement exponential backoff and respect rate limits
  </Accordion>
</AccordionGroup>

### Validation Errors

<AccordionGroup>
  <Accordion title="missing_content">
    **Status**: 400\
    **Cause**: No prompt, script, voice\_url, or avatar\_url provided\
    **Solution**: Provide at least one content parameter
  </Accordion>

  <Accordion title="missing_voice">
    **Status**: 400\
    **Cause**: Script provided but no voice specified\
    **Solution**: Add voice\_id or voice\_url when using script
  </Accordion>

  <Accordion title="invalid_voice_id">
    **Status**: 400\
    **Cause**: Specified voice\_id not found\
    **Solution**: Use GET /voice/list to get valid voice IDs
  </Accordion>

  <Accordion title="invalid_avatar_id">
    **Status**: 400\
    **Cause**: Specified avatar\_id not found\
    **Solution**: Use GET /avatar/list to get valid avatar IDs
  </Accordion>

  <Accordion title="invalid_format">
    **Status**: 400\
    **Cause**: Invalid video format specified\
    **Solution**: Use 'vertical', 'square', or 'ads'
  </Accordion>
</AccordionGroup>

### Resource Errors

<AccordionGroup>
  <Accordion title="insufficient_credits">
    **Status**: 402\
    **Cause**: Not enough credits for the operation\
    **Solution**: Purchase more credits or reduce resource usage
  </Accordion>

  <Accordion title="job_not_found">
    **Status**: 404\
    **Cause**: Job ID doesn't exist\
    **Solution**: Verify the job\_id is correct
  </Accordion>

  <Accordion title="unauthorized_job">
    **Status**: 403\
    **Cause**: Job doesn't belong to your workspace\
    **Solution**: Only access jobs created by your API key
  </Accordion>

  <Accordion title="video_not_found">
    **Status**: 404\
    **Cause**: Video ID doesn't exist\
    **Solution**: Verify the video\_id is correct
  </Accordion>
</AccordionGroup>

## Error Handling Best Practices

### 1. Always Check Status Codes

```javascript theme={null}
const response = await fetch('https://app.hoox.video/api/public/v1/generation/start', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hx_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(requestData)
});

if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error);
  
  // Handle specific error codes
  if (error.details?.[0]?.code === 'insufficient_credits') {
    // Redirect to billing page
  } else if (error.details?.[0]?.code === 'rate_limit_exceeded') {
    // Implement retry with backoff
  }
  
  throw new Error(`API Error: ${error.error}`);
}
```

### 2. Implement Retry Logic

```javascript theme={null}
async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - wait before retry
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = resetTime ? (parseInt(resetTime) * 1000) - Date.now() : 1000 * attempt;
        
        if (attempt < maxRetries) {
          await new Promise(resolve => setTimeout(resolve, Math.max(waitTime, 0)));
          continue;
        }
      }
      
      if (!response.ok) {
        const error = await response.json();
        throw new Error(`API Error: ${error.error}`);
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      // Exponential backoff for other errors
      await new Promise(resolve => 
        setTimeout(resolve, 1000 * Math.pow(2, attempt - 1))
      );
    }
  }
}
```

### 3. Handle Validation Errors

```javascript theme={null}
function handleValidationErrors(errorResponse) {
  const errors = errorResponse.details || [];
  const fieldErrors = {};
  
  errors.forEach(error => {
    if (error.field) {
      fieldErrors[error.field] = error.message;
    }
  });
  
  return fieldErrors;
}

// Usage
try {
  const response = await fetch(apiUrl, options);
  if (!response.ok) {
    const error = await response.json();
    
    if (response.status === 400) {
      const fieldErrors = handleValidationErrors(error);
      // Update UI to show field-specific errors
      console.log('Validation errors:', fieldErrors);
    }
  }
} catch (error) {
  console.error('Request failed:', error);
}
```

### 4. Monitor Rate Limits

```javascript theme={null}
function checkRateLimits(response) {
  const limit = response.headers.get('X-RateLimit-Limit');
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');
  
  console.log(`Rate limit: ${remaining}/${limit}, resets at ${new Date(reset * 1000)}`);
  
  // Warn when approaching limit
  if (parseInt(remaining) < 10) {
    console.warn('Approaching rate limit!');
  }
}
```

## Webhook Error Handling

When using webhooks, you may receive error notifications:

```json theme={null}
{
  "job_id": "run_01234567890abcdef",
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "Video generation failed due to insufficient credits"
  }
}
```

Handle webhook errors in your endpoint:

```javascript theme={null}
app.post('/webhook/hoox', (req, res) => {
  const { job_id, status, error, result } = req.body;
  
  if (status === 'failed') {
    console.error(`Job ${job_id} failed:`, error);
    
    // Handle specific error codes
    switch (error.code) {
      case 'insufficient_credits':
        // Notify user about credit shortage
        break;
      case 'generation_failed':
        // Log for investigation
        break;
      default:
        // Generic error handling
    }
  } else if (status === 'completed') {
    // Handle successful completion
    console.log(`Job ${job_id} completed:`, result);
  }
  
  res.status(200).send('OK');
});
```

<Tip>
  Always implement proper error handling and logging in production applications to diagnose issues quickly.
</Tip>


# Introduction
Source: https://docs.hoox.video/introduction

Welcome to the Hoox API documentation

## What is the Hoox API?

The Hoox API allows you to generate videos programmatically using our advanced artificial intelligence technology. Create videos from scripts or prompts, with voiceovers, avatars, automatic media integration and much more.

<CardGroup>
  <Card title="Video Generation" icon="video" href="/video-generation/overview">
    Create videos from scripts, prompts, or existing content
  </Card>

  <Card title="Custom Export" icon="download" href="/video-export/overview">
    Export your videos in different formats and resolutions
  </Card>

  <Card title="Resources" icon="microphone" href="/voice/list">
    Access our library of voices and avatars
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/overview">
    Receive real-time notifications about your generations
  </Card>
</CardGroup>

## Prerequisites

To use the Hoox API, you must:

1. **Have a Pro plan or higher** - API access is available from the Pro plan onward
2. **Generate an API key** - Available in your workspace settings
3. **Have credits** - Each generation and export consumes credits

<Warning>
  The Hoox API is currently in beta. Some features may evolve.
</Warning>

## Limits and Quotas

| Plan | Requests/minute |
| - | - |
| Pro | 100 |
| Enterprise | 100 |

## Need Help?

<CardGroup>
  <Card title="Technical Support" icon="headset" href="mailto:support@hoox.video">
    Contact our team for any technical questions
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/hoox">
    Join our developer community
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.hoox.video/quickstart

Create your first AI video in minutes with the complete workflow

## API Workflow Overview

The Hoox API follows a simple workflow to create professional videos:

<Steps>
  <Step title="Get Resources">
    Discover available voices and avatars for your videos
  </Step>

  <Step title="Generate Content">
    Create a script or directly generate a video from a prompt
  </Step>

  <Step title="Monitor Progress">
    Track generation status until completion
  </Step>

  <Step title="Export Video">
    Export your video to downloadable MP4 format
  </Step>
</Steps>

## Step 1: Get your API key

1. Log in to your [Hoox dashboard](https://app.hoox.video)
2. Go to **Your Space** > **Settings** > **API**
3. Click **Generate API Key**
4. **Copy and save** your key (it will only be shown once)

<Warning>
  Keep your API key secret! Never share it publicly or commit it to version control.
</Warning>

## Step 2: Discover Available Resources

Before creating videos, explore the voices and avatars available for your account:

### Get Available Voices

Explore all available voices using the [voices API endpoint](/api-reference/voice/list):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/voice/list" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.hoox.video/api/public/v1/voice/list',
      headers={'Authorization': 'Bearer your_api_key'}
  )

  voices = response.json()['voices']
  print(f"Found {len(voices)} voices")

  # Find a professional English voice
  professional_voices = [
      voice for voice in voices 
      if voice['language'] == 'en' and 'professional' in voice['tags']
  ]

  selected_voice = professional_voices[0] if professional_voices else voices[0]
  print(f"Selected voice: {selected_voice['name']} ({selected_voice['id']})")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/voice/list', {
    headers: {
      'Authorization': 'Bearer your_api_key'
    }
  });

  const data = await response.json();
  const voices = data.voices;

  // Find a professional English voice
  const selectedVoice = voices.find(voice => 
    voice.language === 'en' && voice.tags.includes('professional')
  ) || voices[0];

  console.log(`Selected voice: ${selectedVoice.name} (${selectedVoice.id})`);
  ```
</CodeGroup>

### Get Available Avatars

Discover available avatars using the [avatars API endpoint](/api-reference/avatar/list):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/avatar/list?place=office&action=presenting" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://app.hoox.video/api/public/v1/avatar/list',
      headers={'Authorization': 'Bearer your_api_key'},
      params={'place': 'office', 'action': 'presenting'}
  )

  avatars = response.json()['avatars']
  print(f"Found {len(avatars)} business avatars")

  # Select a business avatar
  selected_avatar = avatars[0] if avatars else None
  if selected_avatar:
      print(f"Selected avatar: {selected_avatar['name']} ({selected_avatar['id']})")
  ```

  ```javascript Node.js theme={null}
  const avatarResponse = await fetch(
    'https://app.hoox.video/api/public/v1/avatar/list?place=office&action=presenting',
    {
      headers: {
        'Authorization': 'Bearer your_api_key'
      }
    }
  );

  const avatarData = await avatarResponse.json();
  const selectedAvatar = avatarData.avatars[0];

  if (selectedAvatar) {
    console.log(`Selected avatar: ${selectedAvatar.name} (${selectedAvatar.id})`);
  }
  ```
</CodeGroup>

## Step 3: Generate Your First Video

You can generate videos in two ways: directly from a prompt, or by first generating a script for review.

### Option A: Direct Video Generation

Generate videos directly from prompts using the [video generation API](/api-reference/generation/start):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/generation/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create an explanatory video about sustainable energy solutions",
      "duration": 60,
      "voice_id": "voice_en_us_female_sarah",
      "avatar_id": "avatar_business_woman_office_1",
      "format": "vertical",
      "web_search": {
        "script": true,
        "images": true
      },
      "animate_image": true
    }'
  ```

  ```python Python theme={null}
  # Direct video generation from prompt
  generation_response = requests.post(
      'https://app.hoox.video/api/public/v1/generation/start',
      headers={
          'Authorization': 'Bearer your_api_key',
          'Content-Type': 'application/json'
      },
      json={
          'prompt': 'Create an explanatory video about sustainable energy solutions',
          'duration': 60,
          'voice_id': selected_voice['id'],  # From step 2
          'avatar_id': selected_avatar['id'] if selected_avatar else None,
          'format': 'vertical',
          'web_search': {
              'script': True,
              'images': True
          },
          'animate_image': True
      }
  )

  generation_data = generation_response.json()
  job_id = generation_data['job_id']
  estimated_cost = generation_data['estimated_credits']

  print(f"Generation started!")
  print(f"Job ID: {job_id}")
  print(f"Estimated cost: {estimated_cost} credits")
  ```

  ```javascript Node.js theme={null}
  // Direct video generation from prompt
  const generationResponse = await fetch('https://app.hoox.video/api/public/v1/generation/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Create an explanatory video about sustainable energy solutions",
      duration: 60,
      voice_id: selectedVoice.id,
      avatar_id: selectedAvatar?.id,
      format: "vertical",
      web_search: {
        script: true,
        images: true
      },
      animate_image: true
    })
  });

  const generationData = await generationResponse.json();
  console.log(`Generation started! Job ID: ${generationData.job_id}`);
  console.log(`Estimated cost: ${generationData.estimated_credits} credits`);
  ```
</CodeGroup>

### Option B: Generate Script First

For better control, generate a script first using the [script generation API](/api-reference/script/generate):

<CodeGroup>
  ```bash cURL theme={null}
  # First, generate a script
  curl -X POST "https://app.hoox.video/api/public/v1/script/generate" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create an explanatory video about sustainable energy solutions",
      "duration": 60,
      "webSearch": true
    }'
  ```

  ```python Python theme={null}
  # Step 1: Generate script for review and cost estimation
  script_response = requests.post(
      'https://app.hoox.video/api/public/v1/script/generate',
      headers={
          'Authorization': 'Bearer your_api_key',
          'Content-Type': 'application/json'
      },
      json={
          'prompt': 'Create an explanatory video about sustainable energy solutions',
          'duration': 60,
          'webSearch': True
      }
  )

  script_data = script_response.json()['data']
  generated_script = script_data['script']
  script_cost = script_data['cost']

  print(f"Script generated! Cost: {script_cost} credits")
  print(f"Script preview: {generated_script[:200]}...")

  # Step 2: Use the script to generate video
  video_response = requests.post(
      'https://app.hoox.video/api/public/v1/generation/start',
      headers={
          'Authorization': 'Bearer your_api_key',
          'Content-Type': 'application/json'
      },
      json={
          'script': generated_script,
          'voice_id': selected_voice['id'],
          'avatar_id': selected_avatar['id'] if selected_avatar else None,
          'format': 'vertical',
          'animate_image': True
      }
  )

  video_data = video_response.json()
  job_id = video_data['job_id']
  print(f"Video generation started! Job ID: {job_id}")
  ```

  ```javascript Node.js theme={null}
  // Step 1: Generate script first
  const scriptResponse = await fetch('https://app.hoox.video/api/public/v1/script/generate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Create an explanatory video about sustainable energy solutions",
      duration: 60,
      webSearch: true
    })
  });

  const scriptData = await scriptResponse.json();
  const generatedScript = scriptData.data.script;
  console.log(`Script generated! Preview: ${generatedScript.substring(0, 200)}...`);

  // Step 2: Use script to generate video
  const videoResponse = await fetch('https://app.hoox.video/api/public/v1/generation/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      script: generatedScript,
      voice_id: selectedVoice.id,
      avatar_id: selectedAvatar?.id,
      format: "vertical",
      animate_image: true
    })
  });

  const videoData = await videoResponse.json();
  console.log(`Video generation started! Job ID: ${videoData.job_id}`);
  ```
</CodeGroup>

Poll the [generation status API](/api-reference/generation/status) until generation is complete:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.hoox.video/api/public/v1/generation/status/{job_id}" \
    -H "Authorization: Bearer your_api_key"
  ```

  ```python Python theme={null}
  import time

  def wait_for_generation_completion(job_id, max_wait=600):
      """Wait for video generation to complete"""
      start_time = time.time()
      
      while time.time() - start_time < max_wait:
          status_response = requests.get(
              f'https://app.hoox.video/api/public/v1/generation/status/{job_id}',
              headers={'Authorization': 'Bearer your_api_key'}
          )
          
          status_data = status_response.json()
          status = status_data['status']
          progress = status_data.get('progress_step', 0)
          current_step = status_data.get('current_step', 'Processing')
          
          print(f"Status: {status} ({progress}%) - {current_step}")
          
          if status == 'completed':
              video_id = status_data['result']['video_id']
              cost = status_data['result']['cost']
              print(f"✅ Generation completed! Video ID: {video_id}, Cost: {cost} credits")
              return video_id
          elif status == 'failed':
              error = status_data.get('error', {})
              print(f"❌ Generation failed: {error.get('message', 'Unknown error')}")
              return None
          
          time.sleep(10)  # Wait 10 seconds before checking again
      
      print("⏰ Generation timed out")
      return None

  # Usage
  video_id = wait_for_generation_completion(job_id)
  ```

  ```javascript Node.js theme={null}
  async function waitForGenerationCompletion(jobId, maxWait = 600000) {
    const startTime = Date.now();
    
    while (Date.now() - startTime < maxWait) {
      const statusResponse = await fetch(
        `https://app.hoox.video/api/public/v1/generation/status/${job_id}`,
        {
          headers: {
            'Authorization': 'Bearer your_api_key'
          }
        }
      );
      
      const statusData = await statusResponse.json();
      const status = statusData.status;
      const progress = statusData.progress_step || 0;
      const currentStep = statusData.current_step || 'Processing';
      
      console.log(`Status: ${status} (${progress}%) - ${currentStep}`);
      
      if (status === 'completed') {
        const videoId = statusData.result.video_id;
        const cost = statusData.result.cost;
        console.log(`✅ Generation completed! Video ID: ${videoId}, Cost: ${cost} credits`);
        return videoId;
      } else if (status === 'failed') {
        const error = statusData.error || {};
        console.log(`❌ Generation failed: ${error.message || 'Unknown error'}`);
        return null;
      }
      
      await new Promise(resolve => setTimeout(resolve, 10000)); // Wait 10 seconds
    }
    
    console.log('⏰ Generation timed out');
    return null;
  }

  // Usage
  const videoId = await waitForGenerationCompletion(generationData.job_id);
  ```
</CodeGroup>

## Step 5: Export the Video

Export your video to a downloadable MP4 file using the [export start API](/api-reference/export/start):

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.hoox.video/api/public/v1/export/start" \
    -H "Authorization: Bearer your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "video_id": "YOUR_VIDEO_ID",
      "format": "vertical"
    }'
  ```

  ```python Python theme={null}
  def export_and_download_video(video_id, format="vertical"):
      """Export video and download the MP4 file"""
      
      # Start export
      export_response = requests.post(
          'https://app.hoox.video/api/public/v1/export/start',
          headers={
              'Authorization': 'Bearer your_api_key',
              'Content-Type': 'application/json'
          },
          json={
              'video_id': video_id,
              'format': format
          }
      )
      
      export_data = export_response.json()
      export_job_id = export_data['job_id']
      print(f"Export started! Job ID: {export_job_id}")
      
      # Wait for export completion
      while True:
          export_status_response = requests.get(
              f'https://app.hoox.video/api/public/v1/export/status/{export_job_id}',
              headers={'Authorization': 'Bearer your_api_key'}
          )
          
          export_status = export_status_response.json()
          status = export_status['status']
          progress = export_status.get('progress', 0)
          
          print(f"Export status: {status} ({progress}%)")
          
          if status == 'completed':
              video_url = export_status['result']['video_url']
              print(f"✅ Export completed! Download URL: {video_url}")
              
              # Download the video
              video_response = requests.get(video_url)
              with open(f'video_{video_id}.mp4', 'wb') as f:
                  f.write(video_response.content)
              
              print(f"📥 Video downloaded as video_{video_id}.mp4")
              return video_url
              
          elif status == 'failed':
              print(f"❌ Export failed: {export_status.get('error', {}).get('message', 'Unknown error')}")
              return None
          
          time.sleep(5)  # Wait 5 seconds before checking again

  # Usage
  if video_id:
      download_url = export_and_download_video(video_id)
  ```

  ```javascript Node.js theme={null}
  async function exportAndDownloadVideo(videoId, format = "vertical") {
    // Start export
    const exportResponse = await fetch('https://app.hoox.video/api/public/v1/export/start', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer your_api_key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        video_id: videoId,
        format: format
      })
    });
    
    const exportData = await exportResponse.json();
    const exportJobId = exportData.job_id;
    console.log(`Export started! Job ID: ${exportJobId}`);
    
    // Wait for export completion
    while (true) {
      const exportStatusResponse = await fetch(
        `https://app.hoox.video/api/public/v1/export/status/${exportJobId}`,
        {
          headers: {
            'Authorization': 'Bearer your_api_key'
          }
        }
      );
      
      const exportStatus = await exportStatusResponse.json();
      const status = exportStatus.status;
      const progress = exportStatus.progress || 0;
      
      console.log(`Export status: ${status} (${progress}%)`);
      
      if (status === 'completed') {
        const videoUrl = exportStatus.result.video_url;
        console.log(`✅ Export completed! Download URL: ${videoUrl}`);
        return videoUrl;
      } else if (status === 'failed') {
        const error = exportStatus.error || {};
        console.log(`❌ Export failed: ${error.message || 'Unknown error'}`);
        return null;
      }
      
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
    }
  }

  // Usage
  if (videoId) {
    const downloadUrl = await exportAndDownloadVideo(videoId);
  }
  ```
</CodeGroup>

<Info>
  **Free first export for API Videos**: Videos created through the API have export costs included in the generation price, so first export is free.
</Info>

## Next Steps

<CardGroup>
  <Card title="Pricing & Credits" href="/costs" icon="credit-card">
    Understand costs and optimize your usage
  </Card>

  <Card title="API Reference" href="/api-reference/generation/start" icon="code">
    Complete API documentation and examples
  </Card>
</CardGroup>


# Script Generation
Source: https://docs.hoox.video/script-generation/overview

Generate high-quality video scripts with AI, enhanced by web content extraction

## How Script Generation Works

The Hoox Script Generation API creates compelling video scripts using AI-powered text generation:

1. **Content Analysis**: Process your prompt and any provided URLs
2. **Web Enhancement**: Optionally search the web for additional context
3. **Script Creation**: Generate natural, engaging scripts tailored to your duration
4. **Image Extraction**: Extract relevant images from web sources for visual elements

## Result

The API returns a generated script along with cost information and extracted images when URLs are provided.

```json theme={null}
{
  "script": "Imagine having your entire world on your wrist. Our new smartwatch collection offers unparalleled health monitoring, fitness tracking, and connectivity.\n\nThe Series 11 starts at 449€, featuring advanced health sensors that detect hypertension, monitor sleep quality, and even track your menstrual cycle with wrist temperature readings.\n\nOur SE 3 delivers essential health features at just 269€, while the Ultra 3 offers premium adventure capabilities at 899€ with satellite communication and up to 72 hours of battery life.\n\nAll models include 5G connectivity, water resistance, and customizable bands in various styles and colors. With Apple Pay, music streaming, and thousands of apps, these watches truly complement your lifestyle.\n\nShare your thoughts below!",
  "cost": 0.2,
  "extractedImages": [
    "https://www.apple.com/v/watch/bs/images/overview/select/product_s11__c23ym6fc09me_large.png",
    "https://www.apple.com/v/watch/bs/images/overview/select/product_se__cbhd710p3auq_large.png",
    "https://www.apple.com/fr/watch/images/overview/select/product_u3__eh9hc0els5g2_large.png",
    "https://www.apple.com/v/watch/bs/images/overview/incentive/incentive_trade_in__dj8ydvx9fx4y_large.jpg"
  ]
}
```

### Image Extraction

When you provide URLs in your request, the system automatically extracts relevant images from those web pages. These extracted image URLs are returned in the `extractedImages` array.

**Why is this useful?** You can directly pass these extracted image URLs to the [Video Generation API](/api-reference/generation/start) using the `media_urls` parameter. This automatically incorporates the images from your source URLs into the generated video, creating a seamless content workflow.

## Parameters

### Required Parameters

#### Prompt

Your main instruction describing what the script should be about. Be specific about the tone, target audience, and key points you want covered.

```json theme={null}
{
  "prompt": "Create an educational script about artificial intelligence that explains its benefits and challenges for everyday users."
}
```

### Optional Parameters

#### Duration

Target script length in seconds (10-600). Defaults to 60 seconds.

```json theme={null}
{
  "prompt": "Create a comprehensive overview of renewable energy sources, covering solar, wind, and hydroelectric power.",
  "duration": 180
}
```

#### URLs

Array of web sources to incorporate into your script (max 10 URLs). The system automatically scrapes and analyzes these URLs without needing to enable web search.

```json theme={null}
{
  "prompt": "Create a compelling product presentation for our new smartwatch collection, highlighting the innovative health tracking features and battery life.",
  "urls": [
    "https://company.com/smartwatch-specs",
    "https://company.com/health-features"
  ]
}
```

<Tip>
  URLs are processed automatically - you don't need to enable `webSearch` for URL content extraction.
</Tip>

#### Web Search

Enable additional web research to enhance script content with current information.

```json theme={null}
{
  "prompt": "Create an informative script covering the latest developments in artificial intelligence",
  "webSearch": true
}
```

## Cost Structure

Transparent credit-based pricing:

* **Base Cost**: 0.1 credit per started 60-second segment
* **URL Processing**: +0.1 credit per URL
* **Web Search**: +0.1 credit when enabled

## Next Steps

<CardGroup>
  <Card title="Video Generation" icon="video" href="/video-generation/overview">
    Learn how to generate videos from your scripts
  </Card>

  <Card title="Script Generation API" icon="code" href="/api-reference/script/generate">
    View the complete API documentation
  </Card>
</CardGroup>


# Video Export
Source: https://docs.hoox.video/video-export/overview

Export generated videos to downloadable MP4 files

## What is Video Export?

Video export is the process of converting your generated video into a downloadable MP4 file. After video generation is complete, you use the export endpoints to create a final video file that you can download, share, or integrate into your applications.

## Export Process

The export process follows these steps:

<Steps>
  <Step title="Complete Video Generation">
    Ensure your video generation is finished with `status: "completed"`.
  </Step>

  <Step title="Start Export">
    Call `/export/start` with the `video_id` from generation.
  </Step>

  <Step title="Monitor Progress">
    Poll `/export/status/{jobId}` to track export progress.
  </Step>

  <Step title="Download Video">
    Get the download URL when export status becomes `completed`.
  </Step>
</Steps>

## Export Formats

You can export videos in different formats optimized for various platforms:

<CardGroup>
  <Card title="Vertical (9:16)" icon="mobile">
    **1080x1920 pixels**
    Perfect for:

    * TikTok
    * Instagram Stories
    * YouTube Shorts
    * Snapchat
  </Card>

  <Card title="Ads (4:5)" icon="rectangle-vertical">
    **1080x1350 pixels**
    Ideal for:

    * Instagram ads
    * Facebook ads
    * Social media advertising
    * Promotional content
  </Card>

  <Card title="Square (1:1)" icon="square">
    **1080x1080 pixels**
    Great for:

    * Instagram feed posts
    * Facebook posts
    * LinkedIn posts
    * Twitter videos
  </Card>

  <Card title="Landscape (16:9)" icon="desktop">
    **1920x1080 pixels**
    Best for:

    * YouTube videos
    * Website embeds
    * Presentations
    * Display content
  </Card>

  <Card title="Custom" icon="sliders">
    **Custom dimensions (up to 5000x5000)**
    Perfect for:

    * Specific platform requirements
    * Custom aspect ratios
    * Non-standard displays
    * Special projects
  </Card>
</CardGroup>

## Export Costs

### High Resolution Surcharge

Videos exported at resolutions exceeding 1080p (width > 1920px OR height > 1080px) incur an additional cost:

<Card title="High Resolution Cost" icon="expand">
  **+2.5 credits per 30 seconds**

  Applies when exporting at resolutions above 1080p (e.g., 4K, custom high-res formats).
  This surcharge is added to the base export cost.
</Card>

<Warning>
  The high resolution surcharge applies to **all videos** (both API-generated and dashboard-created) when exporting at resolutions exceeding 1080p.
</Warning>

### Avatar Quality Models

When your video includes an avatar, you can choose from multiple quality models with different performance and cost characteristics:

<CardGroup>
  <Card title="Standard" icon="zap">
    **Free**

    Basic avatar quality that works well for most use cases. No additional credits required.

    **Best for:**

    * Quick exports
    * Budget-conscious projects
    * Testing and prototyping
  </Card>

  <Card title="Premium" icon="gem">
    **0.8 credits/sec** (avatar visibility)

    Highly realistic and dynamic avatar rendering with enhanced facial expressions and movements.

    **Best for:**

    * Professional content
    * Marketing videos
    * High-quality presentations

    *Available from Start plan*
  </Card>

  <Card title="Ultra" icon="crown">
    **2.3 credits/sec** (avatar visibility)

    Enhanced realism with the highest quality output. Longer processing time for superior results.

    **Best for:**

    * Premium content
    * Flagship campaigns
    * Maximum quality requirements

    *Enterprise plan only*
  </Card>

  <Card title="Veo 3 Fast" icon="google">
    **2.3 credits/sec** (per segment)

    Google Veo 3 Fast model for quick, high-quality generation with AI-powered avatars.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * Fast turnaround
    * AI-generated avatars
    * Modern content creation

    *Available from Start plan*
  </Card>

  <Card title="Veo 3" icon="google">
    **5 credits/sec** (per segment)

    Google Veo 3 standard model for the highest quality AI-generated avatars. Exceptional realism.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * Cutting-edge quality
    * Premium AI content
    * Maximum realism

    *Available from Start plan*
  </Card>

  <Card title="Veo 3 Lite" icon="google">
    **0.5 credits/sec** (720p) · **0.8 credits/sec** (1080p)

    Affordable Google Veo 3 model with good quality at lower cost. 720p for 4s/6s segments, 1080p for 8s segments.

    **Best for:**

    * Cost-effective content
    * High-volume production
    * Good quality at lower price

    *Available from Start plan*
  </Card>

  <Card title="Seedance 2" icon="sparkles">
    **4 credits/sec** (per segment)

    ByteDance Seedance 2 model for high-quality avatar generation with excellent realism.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * High-quality content
    * Realistic avatar rendering
    * Premium productions

    *Available from Pro plan*
  </Card>

  <Card title="Seedance 2 Fast" icon="bolt">
    **3 credits/sec** (per segment)

    ByteDance Seedance 2 Fast model for quick avatar generation with great quality.
    Billed per avatar segment (each segment = 8 seconds).

    **Best for:**

    * Fast turnaround
    * Good quality at speed
    * High-volume production

    *Available from Pro plan*
  </Card>
</CardGroup>

<Note>
  **Model availability:** Not all avatars support all models. Check the `model_available` field when fetching avatars to see which models are supported.
</Note>

### Cost Calculation Examples

**Example 1**: A 60-second API video at standard resolution with 40 seconds of Premium avatar visibility:

* Base export cost: 0 credits (API video - included)
* High-res cost: 0 credits (≤1080p)
* Avatar cost: 40s × 0.8 = 32 credits
* **Total cost**: 32 credits

**Example 2**: A 60-second API video with 3 avatar segments using Veo 3 Fast:

* Base export cost: 0 credits (API video - included)
* High-res cost: 0 credits (≤1080p)
* Avatar cost: 3 segments × 8 seconds × 2.3 = 55.2 credits
* **Total cost**: 55.2 credits

**Example 3**: A 60-second API video exported at 3840x2160 (4K):

* Base export cost: 0 credits (API video - included)
* High-res cost: 2 × 2.5 = 5 credits
* Avatar cost: 0 credits (no avatar)
* **Total cost**: 5 credits

**Example 4**: A 90-second dashboard video at 4K with 60 seconds of Premium avatar visibility:

* Base export cost: 3 × 5 = 15 credits
* High-res cost: 3 × 2.5 = 7.5 credits
* Avatar cost: 60s × 0.8 = 48 credits (avatar visibility)
* **Total cost**: 70.5 credits

## Use Cases

### Content Distribution

```mermaid theme={null}
graph LR
    A[Generate Video] --> B[Export Vertical]
    A --> C[Export Ads]
    A --> D[Export Square]  
    A --> E[Export Landscape]
    B --> F[TikTok/Stories]
    C --> G[Social Ads]
    D --> H[Instagram/Facebook]
    E --> I[YouTube/Website]
```

### Workflow Integration

1. **Automated Publishing**: Export and automatically upload to social platforms
2. **Content Libraries**: Build collections of branded video content
3. **Multi-Platform Distribution**: Create platform-specific versions of each video
4. **Client Delivery**: Provide downloadable videos to clients

<Tip>
  **Free API Exports**: The first export of any video created through the API is completely free. Additional exports or format changes may incur costs depending on your plan.
</Tip>

## Next Steps

<Card title="Export Status API" href="/api-reference/export/status" icon="code">
  View the complete API documentation for export status
</Card>


# Video Generation
Source: https://docs.hoox.video/video-generation/overview

Learn how to generate videos with the Hoox API

## How Video Generation Works

The Hoox API uses advanced AI to generate videos from various inputs:

1. **Content Creation**: From prompts, scripts, or existing media
2. **Voice Synthesis**: Convert text to natural-sounding speech
3. **Visual Assembly**: Combine media, animations, and transitions
4. **Final Rendering**: Export in your desired format

<img alt="Video Generation Flow" />

## Generation Methods

<CardGroup>
  <Card title="Prompt-based" icon="sparkles">
    Generate videos from simple text prompts. The AI creates the script, finds media, and assembles everything.
  </Card>

  <Card title="Script-based" icon="file">
    Provide your own script and let the AI handle voice synthesis and media selection.
  </Card>

  <Card title="Media-based" icon="images">
    Use your own voice recordings or avatar videos as the foundation.
  </Card>

  <Card title="Plan-based" icon="clapperboard">
    Provide a ready-made editing plan and Hoox assembles the video exactly as described, sequence by sequence.
  </Card>
</CardGroup>

## Input Options

### Text Content

Generate videos using text-based inputs. These options are perfect when you want the AI to handle voice synthesis and media selection automatically.

#### Prompt

Provide a simple text prompt and let the AI create everything from scratch - script, media selection, and voice synthesis. Perfect for quick content creation.

```json theme={null}
{
  "prompt": "Create an educational video about renewable energy sources, focusing on solar and wind power",
  "voice_id": "en-US-JennyNeural"
}
```

#### Script

Provide your own detailed script and let the AI handle voice synthesis and media selection. Ideal when you want control over the narrative but need help with production.

```json theme={null}
{
  "script": "Solar energy is one of the most promising renewable energy sources. It harnesses the power of the sun through photovoltaic cells...",
  "voice_id": "en-US-AriaNeural",
}
```

### Media Content

Use your own media assets as the foundation for video generation. These options give you more control over the visual and audio elements of your videos.

#### Voice Recording

Use your own voice recordings as the audio track.

```json theme={null}
{
  "voice_url": "https://your-domain.com/voiceover.mp3"
}
```

#### Avatar Video

Start with an existing avatar video where someone is speaking.

```json theme={null}
{
  "avatar_url": "https://your-domain.com/avatar-speaking.mp4"
}
```

#### Custom Media

The AI will automatically analyze and place your media throughout the video based on the content.

```json theme={null}
{
  "prompt": "A vide oabout my product",
  "voice_id": "en-US-DavisNeural",
  "media_urls": [
    "https://your-domain.com/product-shot.jpg",
    "https://your-domain.com/demo-video.mp4"
  ]
}
```

### Plan Content

Provide a ready-made **editing plan** and skip the AI montage entirely. Instead of letting Hoox decide how the video is cut, which media appears when, and which avatar look is on screen, you describe the montage yourself — sequence by sequence. This is ideal when an agent (or your own app) already knows exactly what the video should look like but shouldn't have to learn how to edit.

<Info>
  When a `sequence_plan` is provided it **takes precedence over everything else**. The video is assembled exactly as planned and `prompt` / `script` are ignored. Everything the plan does *not* specify (word timings, subtitles, music, transitions, and missing B-roll) still stays automatic.
</Info>

The `sequence_plan` is a **flat array of speech blocks** in playback order. It has two levels:

* **Each array entry is a speech block** — one speaker talking continuously (one voice, one parent avatar, one audio track). A block is either fully spoken or fully silent, and its audio index is derived automatically from its position in the array.
* **`sequences`** — the visual fragments inside a block, in playback order. Each one carries a bit of `text`, and optionally its own media and avatar look.

<Warning>
  Split a longer video into **several blocks**, don't cram everything into one. Each block is one continuous take by one speaker, so start a new block whenever the speaker, voice, or avatar changes — and, for longer monologues, break the speech into a handful of blocks rather than a single giant one.
</Warning>

**Defaults keep plans small.** The generation-level `voice_id` and `avatar_id` are used as the defaults for every block and sequence. You only set `voice_id`, `avatar_id`, or `look_id` inside the plan when a specific block or sequence needs to *override* the default — for example a different speaker's voice, or the same person shot in a different look on one sequence.

```json theme={null}
{
  "voice_id": "voice_en_us_female_1",
  "avatar_id": "look_default",
  "sequence_plan": [
    {
      "sequences": [
        { "text": "We waste 3 hours a day.", "media": { "asset_id": "65f0a1b2c3d4e5f6a7b8c9d0", "show": "full" } },
        { "text": "Without even noticing.", "look_id": "look_closeup", "action": "He shakes his head slowly" }
      ]
    },
    {
      "voice_id": "voice_en_us_male_1",
      "look_id": "look_second_speaker",
      "sequences": [
        { "text": "Oh yeah? How come?", "media": { "url": "https://your-domain.com/chart.jpg", "show": "half" } }
      ]
    }
  ]
}
```

**Media** can reference an `asset_id` from your space library or a public `url`, and `show` controls how it covers the avatar (`full`, `half`, `background`, or `hide`). To insert a pause, add a dedicated block with a single silent sequence: `{ "text": null, "duration_ms": 1200 }`.

**Direct the avatar** with `action` on a sequence — a plain-language description of what it does while speaking that fragment (`{ "text": "And that's the trick.", "action": "He leans in and taps the table twice" }`). It is applied at export by the avatar models that accept motion direction (the native models and `premium`).

<Tip>
  Never provide timings for spoken text — Hoox always computes word timings from the generated audio. `duration_ms` is only for silent sequences.
</Tip>

See the [Start Video Generation reference](/api-reference/generation/start) for the full `sequence_plan` schema.

## Advanced Features

### Custom Video Formats

Create videos with custom dimensions tailored to your specific needs. Beyond the standard formats (vertical, square, ads, horizontal), you can specify exact width and height dimensions.

```json theme={null}
{
  "prompt": "Create a product showcase video",
  "voice_id": "en-US-DavisNeural",
  "format": "custom",
  "width": 1200,
  "height": 1600
}
```

<Info>
  Custom dimensions support up to 5000px for both width and height, allowing you to create videos for any platform or display requirement.
</Info>

### Web Search Integration

Enhance your videos with real-time web content. The AI can search the internet during script writing to include current information, or find relevant images like celebrity photos, landmarks, content to enrich your video.

```json theme={null}
{
  "prompt": "Explain cryptocurrency basics",
  "voice_id": "en-US-JennyNeural",
  "webSearch": {
    "script": true,    // Enhance script with web research
    "images": true     // Find relevant images automatically
  }
}
```

### Image Animation

Transform static images into dynamic videos using AI animation. Images from URLs are automatically converted into animated sequences, bringing still photos to life with natural movement and transitions.

```json theme={null}
{
  "script": "The landscape shows beautiful mountains...",
  "voice_id": "en-US-AriaNeural",
  "animate_image": true,
  "animate_image_max": 3        // Limit for cost control
}
```

<Tip>
  Use the `animate_image_max` parameter to control animation costs when using many images.
</Tip>

### Workspace Media Control

Control how workspace media is used:

```json theme={null}
{
  "prompt": "Create a company overview video",
  "voice_id": "en-US-DavisNeural",
  "use_space_media": false,      // Don't use workspace media
  "save_media_to_space": false   // Don't save generated media
}
```

## Next Steps

<CardGroup>
  <Card title="Video Export" icon="download" href="/video-export/overview">
    Learn how to export your generated videos
  </Card>

  <Card title="Generation API Reference" icon="code" href="/api-reference/generation/start">
    Detailed API documentation for video generation
  </Card>
</CardGroup>


# Webhooks Overview
Source: https://docs.hoox.video/webhooks/overview

Get real-time notifications about your video generation and export jobs

## What are Webhooks?

Webhooks allow you to receive real-time notifications when your video generation or export jobs complete. Instead of polling the status endpoint repeatedly, Hoox will send an HTTP POST request to your specified URL when the job finishes.

## Benefits

<CardGroup>
  <Card title="Real-time Updates" icon="bolt">
    Get notified immediately when jobs complete, no need to poll
  </Card>

  <Card title="Reduced API Calls" icon="chart-line-down">
    Save on rate limits by eliminating status polling
  </Card>

  <Card title="Better UX" icon="heart">
    Provide instant feedback to your users
  </Card>

  <Card title="Automation" icon="robot">
    Trigger downstream processes automatically
  </Card>
</CardGroup>

## How Webhooks Work

<Steps>
  <Step title="Configure Webhook URL">
    Include a `webhook_url` in your generation or export request
  </Step>

  <Step title="Job Processing">
    Hoox processes your video generation or export job
  </Step>

  <Step title="Webhook Delivery">
    When the job completes (success or failure), Hoox sends a POST request to your URL
  </Step>

  <Step title="Acknowledgment">
    Your endpoint should respond with a 200 status code to confirm receipt
  </Step>
</Steps>

## Webhook Payload

All webhooks include a `task` field to identify the type of operation. This helps you route and process webhooks correctly.

### Payload Structure by Task Type

| Field | video\_generate | video\_export | avatar\_create | avatar\_edit |
| - | - | - | - | - |
| `task` | ✅ | ✅ | ✅ | ✅ |
| `job_id` | ✅ | ✅ | ❌ | ❌ |
| `avatar_id` | ❌ | ❌ | ✅ | ✅ |
| `look_id` | ❌ | ❌ | ✅ | ✅ |
| `status` | ✅ | ✅ | ✅ | ✅ |
| `result` | ✅ | ✅ | ✅ | ✅ |
| `error` | ✅ (on failure) | ✅ (on failure) | ✅ (on failure) | ✅ (on failure) |

<Info>
  **Key differences:**

  * Video operations use `job_id` (the Trigger.dev run ID)
  * Avatar operations use `avatar_id` and `look_id` instead
  * Always check the `task` field to determine how to process the webhook
</Info>

<Tabs>
  <Tab title="Video Generation">
    ### Successful Generation

    ```json theme={null}
    {
      "task": "video_generate",
      "job_id": "run_01234567890abcdef",
      "status": "completed",
      "result": {
        "video_id": "video_abcdef1234567890",
        "thumbnail_url": "https://cdn.hoox.video/thumbnails/video_123.jpg",
        "cost": 5,
        "created_at": "2024-01-15T10:30:00Z"
      }
    }
    ```

    ### Failed Generation

    ```json theme={null}
    {
      "task": "video_generate",
      "job_id": "run_01234567890abcdef",
      "status": "failed",
      "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Not enough credits to complete video generation"
      }
    }
    ```
  </Tab>

  <Tab title="Video Export">
    ### Successful Export

    ```json theme={null}
    {
      "task": "video_export",
      "job_id": "run_fedcba0987654321",
      "status": "completed", 
      "result": {
        "video_id": "video_abcdef1234567890",
        "download_url": "https://cdn.hoox.video/exports/video_456.mp4",
        "cost": 3,
        "created_at": "2024-01-15T10:35:00Z"
      }
    }
    ```

    ### Failed Export

    ```json theme={null}
    {
      "task": "video_export",
      "job_id": "run_fedcba0987654321",
      "status": "failed",
      "error": {
        "code": "EXPORT_FAILED",
        "message": "Render failed"
      }
    }
    ```
  </Tab>

  <Tab title="Avatar Creation">
    ### Successful Creation

    ```json theme={null}
    {
      "task": "avatar_create",
      "avatar_id": "avatar_abc123",
      "look_id": "look_def456",
      "status": "completed",
      "result": {
        "thumbnail_url": "https://cdn.hoox.video/avatars/look_def456.jpg"
      }
    }
    ```

    ### Failed Creation

    ```json theme={null}
    {
      "task": "avatar_create",
      "avatar_id": "avatar_abc123",
      "look_id": "look_def456",
      "status": "failed",
      "error": {
        "code": "GENERATION_FAILED",
        "message": "Unknown error during generation"
      }
    }
    ```
  </Tab>

  <Tab title="Avatar Edit">
    ### Successful Edit

    ```json theme={null}
    {
      "task": "avatar_edit",
      "avatar_id": "avatar_abc123",
      "look_id": "look_ghi789",
      "status": "completed",
      "result": {
        "thumbnail_url": "https://cdn.hoox.video/avatars/look_ghi789.jpg"
      }
    }
    ```

    ### Failed Edit

    ```json theme={null}
    {
      "task": "avatar_edit",
      "avatar_id": "avatar_abc123",
      "look_id": "look_ghi789",
      "status": "failed",
      "error": {
        "code": "GENERATION_FAILED",
        "message": "Edit failed"
      }
    }
    ```
  </Tab>
</Tabs>

## Setting Up Webhooks

### 1. Create an Endpoint

Your webhook endpoint should:

* Accept POST requests
* Respond with 200 status code
* Process the payload asynchronously if needed

<CodeGroup>
  ```javascript Node.js/Express theme={null}
  app.post('/webhook/hoox', express.json(), (req, res) => {
    const { task, job_id, avatar_id, look_id, status, result, error } = req.body;
    
    console.log(`Webhook received for ${task}: ${status}`);
    
    // Route based on task type
    switch (task) {
      case 'video_generate':
        handleVideoGeneration(job_id, status, result, error);
        break;
      case 'video_export':
        handleVideoExport(job_id, status, result, error);
        break;
      case 'avatar_create':
      case 'avatar_edit':
        handleAvatar(avatar_id, look_id, status, result, error);
        break;
      default:
        console.warn('Unknown task type:', task);
    }
    
    // Always respond with 200
    res.status(200).send('OK');
  });

  function handleVideoGeneration(job_id, status, result, error) {
    if (status === 'completed') {
      console.log('Video generated:', result.video_id);
      updateJobStatus(job_id, 'completed', result);
      notifyUser(job_id, result);
    } else {
      console.error('Generation failed:', error);
      updateJobStatus(job_id, 'failed', null, error);
      notifyUserOfFailure(job_id, error);
    }
  }

  function handleVideoExport(job_id, status, result, error) {
    if (status === 'completed') {
      console.log('Video exported:', result.download_url);
      updateJobStatus(job_id, 'completed', result);
      notifyUser(job_id, result);
    } else {
      console.error('Export failed:', error);
      updateJobStatus(job_id, 'failed', null, error);
      notifyUserOfFailure(job_id, error);
    }
  }

  function handleAvatar(avatar_id, look_id, status, result, error) {
    if (status === 'completed') {
      console.log('Avatar ready:', avatar_id, look_id);
      updateAvatarStatus(avatar_id, look_id, 'completed', result);
      notifyUser(avatar_id, result);
    } else {
      console.error('Avatar failed:', error);
      updateAvatarStatus(avatar_id, look_id, 'failed', null, error);
      notifyUserOfFailure(avatar_id, error);
    }
  }
  ```

  ```python Python/Flask theme={null}
  from flask import Flask, request, jsonify

  @app.route('/webhook/hoox', methods=['POST'])
  def hoox_webhook():
      data = request.get_json()
      
      task = data.get('task')
      job_id = data.get('job_id')
      avatar_id = data.get('avatar_id')
      look_id = data.get('look_id')
      status = data.get('status')
      result = data.get('result')
      error = data.get('error')
      
      print(f"Webhook received for {task}: {status}")
      
      # Route based on task type
      if task == 'video_generate':
          handle_video_generation(job_id, status, result, error)
      elif task == 'video_export':
          handle_video_export(job_id, status, result, error)
      elif task in ['avatar_create', 'avatar_edit']:
          handle_avatar(avatar_id, look_id, status, result, error)
      else:
          print(f"Unknown task type: {task}")
      
      # Always respond with 200
      return jsonify({'status': 'ok'}), 200

  def handle_video_generation(job_id, status, result, error):
      if status == 'completed':
          print(f"Video generated: {result.get('video_id')}")
          update_job_status(job_id, 'completed', result)
          notify_user(job_id, result)
      else:
          print(f"Generation failed: {error}")
          update_job_status(job_id, 'failed', None, error)
          notify_user_of_failure(job_id, error)

  def handle_video_export(job_id, status, result, error):
      if status == 'completed':
          print(f"Video exported: {result.get('download_url')}")
          update_job_status(job_id, 'completed', result)
          notify_user(job_id, result)
      else:
          print(f"Export failed: {error}")
          update_job_status(job_id, 'failed', None, error)
          notify_user_of_failure(job_id, error)

  def handle_avatar(avatar_id, look_id, status, result, error):
      if status == 'completed':
          print(f"Avatar ready: {avatar_id}/{look_id}")
          update_avatar_status(avatar_id, look_id, 'completed', result)
          notify_user(avatar_id, result)
      else:
          print(f"Avatar failed: {error}")
          update_avatar_status(avatar_id, look_id, 'failed', None, error)
          notify_user_of_failure(avatar_id, error)
  ```

  ```php PHP theme={null}
  <?php
  // webhook.php

  // Get the JSON payload
  $payload = json_decode(file_get_contents('php://input'), true);

  $task = $payload['task'] ?? 'unknown';
  $jobId = $payload['job_id'] ?? null;
  $avatarId = $payload['avatar_id'] ?? null;
  $lookId = $payload['look_id'] ?? null;
  $status = $payload['status'];
  $result = $payload['result'] ?? null;
  $error = $payload['error'] ?? null;

  error_log("Webhook received for $task: $status");

  // Route based on task type
  switch ($task) {
      case 'video_generate':
          handleVideoGeneration($jobId, $status, $result, $error);
          break;
      case 'video_export':
          handleVideoExport($jobId, $status, $result, $error);
          break;
      case 'avatar_create':
      case 'avatar_edit':
          handleAvatar($avatarId, $lookId, $status, $result, $error);
          break;
      default:
          error_log("Unknown task type: $task");
  }

  function handleVideoGeneration($jobId, $status, $result, $error) {
      if ($status === 'completed') {
          $videoId = $result['video_id'] ?? '';
          error_log("Video generated: $videoId");
          updateJobStatus($jobId, 'completed', $result);
          notifyUser($jobId, $result);
      } else {
          error_log("Generation failed: " . $error['message']);
          updateJobStatus($jobId, 'failed', null, $error);
          notifyUserOfFailure($jobId, $error);
      }
  }

  function handleVideoExport($jobId, $status, $result, $error) {
      if ($status === 'completed') {
          $downloadUrl = $result['download_url'] ?? '';
          error_log("Video exported: $downloadUrl");
          updateJobStatus($jobId, 'completed', $result);
          notifyUser($jobId, $result);
      } else {
          error_log("Export failed: " . $error['message']);
          updateJobStatus($jobId, 'failed', null, $error);
          notifyUserOfFailure($jobId, $error);
      }
  }

  function handleAvatar($avatarId, $lookId, $status, $result, $error) {
      if ($status === 'completed') {
          error_log("Avatar ready: $avatarId/$lookId");
          updateAvatarStatus($avatarId, $lookId, 'completed', $result);
          notifyUser($avatarId, $result);
      } else {
          error_log("Avatar failed: " . $error['message']);
          updateAvatarStatus($avatarId, $lookId, 'failed', null, $error);
          notifyUserOfFailure($avatarId, $error);
      }
  }

  // Always respond with 200
  http_response_code(200);
  echo 'OK';
  ?>
  ```
</CodeGroup>

### 2. Use in API Calls

Include your webhook URL when starting jobs:

<CodeGroup>
  ```javascript Generation theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/generation/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Create a video about space exploration",
      voice_id: "en-US-JennyNeural",
      webhook_url: "https://your-app.com/webhook/hoox"
    })
  });

  // Will receive webhook with task: "video_generate"
  ```

  ```javascript Export theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/export/start', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_id: "video_123",
      format: "vertical",
      webhook_url: "https://your-app.com/webhook/hoox"
    })
  });

  // Will receive webhook with task: "video_export"
  ```

  ```javascript Avatar Create theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/avatar/create', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: "Professional business avatar in modern office",
      style: "studio",
      webhook_url: "https://your-app.com/webhook/hoox"
    })
  });

  // Will receive webhook with task: "avatar_create"
  ```

  ```javascript Avatar Edit theme={null}
  const response = await fetch('https://app.hoox.video/api/public/v1/avatar/edit', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer hx_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      avatar_id: "avatar_abc123",
      look_id: "look_def456",
      prompt: "Casual outfit in coffee shop",
      style: "podcast",
      webhook_url: "https://your-app.com/webhook/hoox"
    })
  });

  // Will receive webhook with task: "avatar_edit"
  ```
</CodeGroup>

## Security Considerations

### 1. Validate Requests

Verify that webhook requests are coming from Hoox:

```javascript theme={null}
// Check User-Agent header
const userAgent = req.headers['user-agent'];
if (!userAgent || !userAgent.includes('Hoox-API')) {
  return res.status(401).send('Unauthorized');
}

// Check for Hoox webhook header
const isHooxWebhook = req.headers['x-hoox-webhook'];
if (isHooxWebhook !== 'true') {
  return res.status(401).send('Unauthorized');
}
```

### 2. Use HTTPS

Always use HTTPS URLs for your webhook endpoints to ensure data is encrypted in transit.

### 3. Implement Idempotency

Handle duplicate webhook deliveries gracefully:

```javascript theme={null}
const processedJobs = new Set();

app.post('/webhook/hoox', (req, res) => {
  const { task, job_id, avatar_id, look_id } = req.body;
  
  // Create unique ID based on task type
  const uniqueId = task === 'avatar_create' || task === 'avatar_edit' 
    ? `${avatar_id}:${look_id}` 
    : job_id;
  
  // Check if we've already processed this webhook
  if (processedJobs.has(uniqueId)) {
    console.log(`Duplicate webhook for ${uniqueId}, ignoring`);
    return res.status(200).send('OK');
  }
  
  // Process the webhook
  processWebhook(req.body);
  
  // Mark as processed
  processedJobs.add(uniqueId);
  
  res.status(200).send('OK');
});
```

## Retry Behavior

Hoox will retry webhook deliveries if your endpoint:

* Returns a non-2xx status code
* Times out (after 10 seconds)
* Is unreachable

**Retry Schedule:**

* 1st retry: After 1 second
* 2nd retry: After 2 seconds
* 3rd retry: After 4 seconds
* **Maximum**: 3 retry attempts

<Warning>
  If all retries fail, the webhook will be discarded. Ensure your endpoint is reliable and responds quickly.
</Warning>

## Testing Webhooks

### 1. Use ngrok for Local Development

```bash theme={null}
# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

# Use the HTTPS URL in your webhook_url
# https://abc123.ngrok.io/webhook/hoox
```

### 2. Webhook Testing Tools

* **RequestBin**: Create temporary endpoints to inspect payloads
* **Webhook.site**: Test and debug webhook deliveries
* **Postman**: Mock webhook requests for testing

### 3. Test Endpoint

Create a simple test endpoint to verify webhook delivery:

```javascript theme={null}
app.post('/webhook/test', (req, res) => {
  console.log('Webhook Headers:', req.headers);
  console.log('Webhook Body:', JSON.stringify(req.body, null, 2));
  console.log('Task Type:', req.body.task);
  
  // Log different IDs based on task type
  if (req.body.task === 'avatar_create' || req.body.task === 'avatar_edit') {
    console.log('Avatar ID:', req.body.avatar_id);
    console.log('Look ID:', req.body.look_id);
  } else {
    console.log('Job ID:', req.body.job_id);
  }
  
  res.status(200).send('Webhook received successfully');
});
```

## Best Practices

<AccordionGroup>
  <Accordion title="Task-Based Routing">
    * Always check the `task` field first to route webhooks correctly
    * Use different handlers for different task types
    * Validate that required fields exist based on task type
    * For avatars: use `avatar_id` and `look_id`
    * For videos: use `job_id`
  </Accordion>

  <Accordion title="Response Time">
    * Respond with 200 status as quickly as possible
    * Process heavy operations asynchronously
    * Use queues for complex workflows
  </Accordion>

  <Accordion title="Error Handling">
    * Log all webhook deliveries for debugging
    * Handle malformed payloads gracefully
    * Implement monitoring and alerting
    * Check for required fields based on task type
  </Accordion>

  <Accordion title="Scalability">
    * Use load balancers for high-volume webhooks
    * Implement rate limiting on your endpoint
    * Consider using message queues for processing
  </Accordion>
</AccordionGroup>

## Common Issues

| Issue | Cause | Solution |
| - | - | - |
| Webhooks not received | Endpoint unreachable | Check URL and firewall settings |
| Duplicate processing | No idempotency check | Implement unique ID tracking (job\_id or avatar\_id:look\_id) |
| Slow processing | Heavy operations in handler | Move to background jobs |
| Missing webhooks | Endpoint returning errors | Fix endpoint logic and status codes |
| Wrong task routing | Not checking task field | Always check the `task` field first |
| Missing IDs | Accessing wrong fields | Use `job_id` for videos, `avatar_id`/`look_id` for avatars |

<Tip>
  Always test your webhook endpoints thoroughly before using them in production.
</Tip>