MAKEUGC PLATFORM API · DOCS V2

Custom avatars

Create an avatar from a portrait and an optional voice sample, then use it in talking-actor videos.

Workflow

Prepare a portrait and, optionally, a voice sample.
Submit multipart/form-data with files or public URL strings.
Save data.avatar_id and use it as avatar_id on /video/generate.

Requires a subscription with custom-avatar access and 1 API credit unit (100 displayed credits).

Maximum uploaded file size: 10 MiB per file. Do not manually set Content-Type when sending FormData; the client must generate the multipart boundary.

Example IDs and media URLs are placeholders. Replace them with values from your account and accessible media files.

Create a custom avatar #

POST /custom-avatar/generate

This endpoint returns avatar details directly. There is no separate custom-avatar status endpoint.

Form fields

Parameter	Description
`image` file \| string Required	Portrait image file (at most 10 MiB) or public image URL.
`voice` file \| string Optional	Voice sample file (at most 10 MiB) or public audio URL. Omit to use an assigned voice.

Request example

cURL

curl --fail-with-body --max-time 120 -X POST "https://app.makeugc.ai/api/platform/custom-avatar/generate" \
  -H "X-Api-Key: $MAKEUGC_API_KEY" \
  --form 'image=https://your-cdn.example/portrait.jpg' \
  --form 'voice=https://your-cdn.example/voice.mp3'

JavaScript

// Run on your server with Node.js 20+.
const apiKey = process.env.MAKEUGC_API_KEY;
if (!apiKey) throw new Error("Set MAKEUGC_API_KEY first");

const form = new FormData();
form.append("image", "https://your-cdn.example/portrait.jpg");
form.append("voice", "https://your-cdn.example/voice.mp3");

const response = await fetch("https://app.makeugc.ai/api/platform/custom-avatar/generate", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
  },
  body: form,
  signal: AbortSignal.timeout(120000),
});
const text = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${text} (request ${response.headers.get("x-request-id")})`);
}
const result = JSON.parse(text);
console.log(result);

Python

# Install the requests package before running.
import os
import requests

payload = {
    "image": "https://your-cdn.example/portrait.jpg",
    "voice": "https://your-cdn.example/voice.mp3"
}

response = requests.post(
    "https://app.makeugc.ai/api/platform/custom-avatar/generate",
    headers={"X-Api-Key": os.environ["MAKEUGC_API_KEY"]},
    files={key: (None, value) for key, value in payload.items()},
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}: {response.text} "
                       f"(request {response.headers.get('x-request-id')})")
print(response.json())

200 response example

JSON response

{
  "status": true,
  "data": {
    "status": true,
    "message": "Custom avatar created",
    "avatar_id": "avatar_123",
    "thumbnail_url": "https://your-cdn.example/portrait.jpg",
    "audio_url": "https://your-cdn.example/voice.mp3",
    "selected_voice_id": "voice_123"
  }
}

All requests require X-Api-Key. See errors & retries for unsuccessful responses.