Create Avatar

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"
  }'

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())

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);

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"
  }'

{
  "avatar_id": "avtr_123",
  "look_id": "look_abc"
}

{
  "error": "Validation failed",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "prompt is required",
      "field": "prompt"
    }
  ]
}

{
  "error": "Insufficient credits",
  "required": 2,
  "available": 1
}

POST

api

public

avatar

create

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"
  }'

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())

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);

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"
  }'

{
  "avatar_id": "avtr_123",
  "look_id": "look_abc"
}

{
  "error": "Validation failed",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "prompt is required",
      "field": "prompt"
    }
  ]
}

{
  "error": "Insufficient credits",
  "required": 2,
  "available": 1
}

Overview

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

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

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

Authentication

This endpoint requires API key authentication. Include your API key in the Authorization header.

Request Body

string

Text prompt describing the avatar to generate. If provided, prompt-based generation takes priority over images.

string

default:"iphone"

Avatar style. Available options: iphone, selfie, podcast, car, conference. Optional, defaults to iphone.

string

default:"vertical"

Image format: vertical (9:16) or horizontal (16:9). Only used for prompt-based generation.

string

Custom name for the avatar.

string

Place or context for the avatar (e.g., “office”, “studio”).

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.

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.

string

default:"2K"

Output image resolution: 2K or 4K. Optional, defaults to 2K. Note that 4K generation costs more credits.

string

URL to receive webhook notifications when generation completes.

Response

string

Unique identifier for the created avatar.

string

Unique identifier for the first look of the avatar. For prompt-based generation, this look will be in “pending” status initially.

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"
  }'

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())

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);

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"
  }'

{
  "avatar_id": "avtr_123",
  "look_id": "look_abc"
}

{
  "error": "Validation failed",
  "details": [
    {
      "code": "INVALID_VALUE",
      "message": "prompt is required",
      "field": "prompt"
    }
  ]
}

{
  "error": "Insufficient credits",
  "required": 2,
  "available": 1
}

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

Check Status: Use /avatar/status endpoint to monitor the generation progress
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)

Script

Generation

Export

Avatar

Voices

Folder

Assets

Overview

Authentication

Request Body

Response

Creation Methods

1. Prompt-based Creation

2. Image-based Creation

Credit Costs

Next Steps

Error Codes

​Overview

​Authentication

​Request Body

​Response

​Creation Methods

​1. Prompt-based Creation

​2. Image-based Creation

​Credit Costs

​Next Steps

​Error Codes

Overview

Authentication

Request Body

Response

Creation Methods

1. Prompt-based Creation

2. Image-based Creation

Credit Costs

Next Steps

Error Codes