Skip to content
Developers
API docs / Features

MAKEUGC PLATFORM API · DOCS V2

Gestures

Animate a still character with a short, natural gesture.

Workflow

  1. Provide a public image URL and a motion prompt.
  2. Submit the generation and save data.id.
  3. Poll for the final video.
Each accepted generation reserves 0.5 API credit units (50 display credits). An explicit upstream 4xx rejection releases the reservation; an ambiguous submission does not.
Send X-Api-Key on every MakeUGC request. POST operations require an active paid subscription and a positive credit balance; custom voice creation also requires a plan with custom voices.
Requests are strict JSON: unknown fields, user_id and webhook_url are rejected. Use polling for jobs; these endpoints do not send webhooks.
The outer status boolean indicates request success. Most jobs use data.status: processing, completed or failed; Upscale documents its own statuses. Poll every 5–10 seconds and require a non-empty result URL (or voice_id) before using output.
API credit units × 100 = website display credits. A timeout, network error or 5xx may occur after acceptance: do not automatically resubmit a paid operation. If submission_unknown is true, check the project or contact support with x-request-id; reserved credits remain held until the result is resolved.

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

Generate gestures #

POST /gestures/generate

Animate a person in a reference image using a motion description.

Request body

Parameter Description
project_id
string
Optional 		Existing project owned by your account. Omit to create one.

Allowed: At least 1 characters; Up to 256 characters

prompt
string
Required 		prompt input.

Allowed: At least 1 characters; Up to 2000 characters

image_url
string
Required 		Public HTTP(S) media URL. Private addresses, credentials and data URIs are not accepted.

Request example

cURL 
curl --fail-with-body --max-time 120 -X POST "https://app.makeugc.ai/api/platform/gestures/generate" \
  -H "X-Api-Key: $MAKEUGC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "project_id": "project_123",
  "image_url": "https://your-cdn.example/product.jpg",
  "prompt": "The person smiles and gently waves toward the camera."
}'
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/gestures/generate", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "project_id": "project_123",
  "image_url": "https://your-cdn.example/product.jpg",
  "prompt": "The person smiles and gently waves toward the camera."
}),
  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 = {
    "project_id": "project_123",
    "image_url": "https://your-cdn.example/product.jpg",
    "prompt": "The person smiles and gently waves toward the camera."
}

response = requests.post(
    "https://app.makeugc.ai/api/platform/gestures/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,
  "data": {
    "id": "job_123",
    "project_id": "project_123",
    "status": "processing",
    "credits_charged": 0.5
  }
}

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

Get gesture status #

GET /gestures/status

Poll the submitted gesture job until video_url is available.

Parameters

Parameter Description
id
string · query
Required 		id input.

Allowed: At least 1 characters; Up to 256 characters

Request example

cURL 
curl --fail-with-body --max-time 120 -X GET "https://app.makeugc.ai/api/platform/gestures/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/gestures/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/gestures/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,
  "data": {
    "id": "job_123",
    "project_id": "project_123",
    "status": "completed",
    "video_url": "https://your-cdn.example/result.mp4"
  }
}

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