Skip to main content
POST
https://app.hoox.video
/
api
/
public
/
v1
/
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",
    "webhook_url": "https://example.com/webhooks/avatar"
  }'

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

​
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).
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

​
prompt
string
Text prompt describing the avatar to generate. If provided, prompt-based generation takes priority over images.
​
style
string
default:"iphone"
Avatar style. Available options: iphone, selfie, podcast, car, conference. Optional, defaults to iphone.
​
format
string
default:"vertical"
Image format: vertical (9:16) or horizontal (16:9). Only used for prompt-based generation.
​
name
string
Custom name for the avatar.
​
place
string
Place or context for the avatar (e.g., “office”, “studio”).
​
images
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.
​
elementImages
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.
​
webhook_url
string
URL to receive webhook notifications when generation completes.

​
Response

​
avatar_id
string
Unique identifier for the created avatar.
​
look_id
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",
    "webhook_url": "https://example.com/webhooks/avatar"
  }'

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

​
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: 2 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)