Skip to content
Developers
API docs / Features

MAKEUGC PLATFORM API · DOCS V2

Talking actors

Turn a script into an avatar video using a stock or custom actor and your choice of voice.

Workflow

  1. List avatars and copy an avatar id.
  2. Choose a voice or use the avatar’s default voice.
  3. Submit the script and save data.id.
  4. Poll /video/status until the video is ready.
Generation costs 1 API credit unit (100 displayed credits). The default script limit is 1,500 characters.
Audio priority: voice_url → voice_id → the avatar’s default voice. voice_script is still required when supplying audio.

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

List avatars #

GET /video/avatars

List template avatars and custom avatars available to the API-key account.

Parameters

Parameter Description
gender
string · query
Optional 		Case-insensitive gender filter, for example Female.

Request example

cURL 
curl --fail-with-body --max-time 120 -X GET "https://app.makeugc.ai/api/platform/video/avatars" \
  -H "X-Api-Key: $MAKEUGC_API_KEY"
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 response = await fetch("https://app.makeugc.ai/api/platform/video/avatars", {
  method: "GET",
  headers: {
    "X-Api-Key": apiKey,
  },
  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

response = requests.get(
    "https://app.makeugc.ai/api/platform/video/avatars",
    headers={"X-Api-Key": os.environ["MAKEUGC_API_KEY"]},
    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,
  "message": "Avatars fetched",
  "data": [
    {
      "id": "avatar_123",
      "name": "Example actor",
      "thumbnail": "https://your-cdn.example/actor.jpg",
      "gender": "Female",
      "skin": "",
      "age_range": "",
      "type": ""
    }
  ]
}

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

Generate a talking-actor video #

POST /video/generate

Submit a video job. A successful response means generation has started.

Request body

Parameter Description
avatar_id
string
Required 		An id from the avatar list.
voice_script
string
Required 		Spoken script. Required even when voice_url is provided.

Allowed: Up to 1,500 characters by default

video_name
string
Optional 		Video and project name.

Default: API Generated Video

voice_url
string
Optional 		Public HTTP(S) audio URL; must be accessible and at most 120 seconds. Skips text-to-speech.
voice_id
string
Optional 		Use the id returned by GET /video/voices, not its voiceId field.
voice_settings
object
Optional 		Optional text-to-speech settings; supply the full settings object when overriding defaults.
voice_settings.stability
number
Optional 		Voice stability.

Allowed: 0–1

Default: 0.75

voice_settings.similarity_boost
number
Optional 		Voice similarity.

Allowed: 0–1

Default: 0.4

voice_settings.style
number
Optional 		Style intensity.

Allowed: 0–1

Default: 0

voice_settings.use_speaker_boost
boolean
Optional 		Speaker boost.

Default: true

voice_settings.speed
number
Optional 		Speech speed multiplier.

Default: 1

webhook_url
string
Optional 		Public HTTP(S) callback URL. Use status polling as a fallback.

Request example

cURL 
curl --fail-with-body --max-time 120 -X POST "https://app.makeugc.ai/api/platform/video/generate" \
  -H "X-Api-Key: $MAKEUGC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "avatar_id": "AVATAR_ID",
  "voice_script": "Meet your new favorite everyday coffee cup.",
  "video_name": "Coffee cup introduction"
}'
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 response = await fetch("https://app.makeugc.ai/api/platform/video/generate", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "avatar_id": "AVATAR_ID",
  "voice_script": "Meet your new favorite everyday coffee cup.",
  "video_name": "Coffee cup introduction"
}),
  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 = {
    "avatar_id": "AVATAR_ID",
    "voice_script": "Meet your new favorite everyday coffee cup.",
    "video_name": "Coffee cup introduction"
}

response = requests.post(
    "https://app.makeugc.ai/api/platform/video/generate",
    headers={"X-Api-Key": os.environ["MAKEUGC_API_KEY"]},
    json=payload,
    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,
  "message": "Video generation started",
  "data": {
    "id": "video_123"
  }
}

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

Get video status #

GET /video/status

Poll every 5–10 seconds. Stop on failed, or completed with a non-empty URL. The outer status boolean describes the API request; data.status describes the job.

While processing, data.status is processing and url is absent. On failure, data.status is failed; a reason may be included. Save output files if you need permanent access.

Parameters

Parameter Description
id
string · query
Required 		Job ID returned by the matching generation endpoint.

Request example

cURL 
curl --fail-with-body --max-time 120 -X GET "https://app.makeugc.ai/api/platform/video/status?id=ID" \
  -H "X-Api-Key: $MAKEUGC_API_KEY"
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 response = await fetch("https://app.makeugc.ai/api/platform/video/status?id=ID", {
  method: "GET",
  headers: {
    "X-Api-Key": apiKey,
  },
  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

response = requests.get(
    "https://app.makeugc.ai/api/platform/video/status?id=ID",
    headers={"X-Api-Key": os.environ["MAKEUGC_API_KEY"]},
    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,
  "message": "Video is completed",
  "data": {
    "status": "completed",
    "url": "https://your-cdn.example/result.mp4"
  }
}

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