Skip to main content

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

From Prompt

Create a brand new avatar using a text prompt and a visual style.

From Images

Build an avatar instantly from your own reference images. No generation cost.

Edit Look

Generate a new look from an existing one using a prompt and optional extra images.

Status & Webhooks

Track generation status via polling or receive webhooks on completion/failure.

​
Endpoints

​
Create from Prompt

POST /api/public/v1/avatar/create Request body: 
{
  "prompt": "Young entrepreneur in a modern office, confident smile",
  "style": "iphone",
  "format": "vertical",
  "name": "Alex",
  "place": "office",
  "elementImages": [
    "https://your-domain.com/logo.png"
  ],
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
Response: 
{
  "avatar_id": "avtr_abc",
  "look_id": "look_123"
}
Creation costs 2 credits. Status starts as pending and becomes ready or error.

​
Create from Images

POST /api/public/v1/avatar/create Request body: 
{
  "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: 
{
  "avatar_id": "avtr_xyz",
  "look_id": "look_a"
}
No generation cost; looks are created instantly with status ready.

​
Edit an Avatar Look

POST /api/public/v1/avatar/edit Request body: 
{
  "avatar_id": "avtr_abc",
  "look_id": "look_123",
  "prompt": "Same person, podcast scene, warm cinematic lighting",
  "style": "podcast",
  "format": "vertical",
  "images": [
    "https://your-domain.com/extra-reference.jpg"
  ],
  "webhook_url": "https://your-domain.com/webhooks/avatar"
}
Response: 
{
  "avatar_id": "avtr_abc",
  "look_id": "look_edit_789"
}
Editing costs 2 credits per new look. A new look is created in pending status and updated to ready or error.

​
Status & Webhooks

​
Poll Generation Status

GET /api/public/v1/avatar/status?avatar_id={avatarId}&look_id={lookId} Example response: 
{
  "avatar_id": "avtr_abc",
  "look_id": "look_edit_789",
  "status": "completed",
  "result": {
    "thumbnail_url": "https://media.hoox.video/…/image.jpg"
  }
}

​
Webhook Payloads

On success: 
{
  "job_id": "look_edit_789",
  "status": "completed",
  "result": { "thumbnail_url": "https://media.hoox.video/.../image.jpg" }
}
On failure: 
{
  "job_id": "look_edit_789",
  "status": "failed",
  "error": { "code": "GENERATION_FAILED", "message": "Edit failed" }
}
Provide a webhook_url in the request body to receive asynchronous updates. Otherwise, use the status endpoint to poll.

​
Next Steps

API Reference

Detailed endpoints for avatar creation and editing

Video Generation Overview

Generate videos using your avatars