MAKEUGC PLATFORM API · DOCS V2

Templates

Generate product videos from the current app template catalog, with reproducible variation selection.

Workflow

List templates and inspect require_fields.
Provide the requested product, actor, voice and text inputs.
Choose a seed, model, duration and aspect ratio, then generate.
Save the returned variation choices and poll for the video.

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.

List templates #

GET /templates/list

List current app templates, preview media, categories and require_fields for each template.

Parameters

Parameter	Description
`category` string · query Optional	category input. Allowed: `Up to 200 characters`

Request example

cURL

curl --fail-with-body --max-time 120 -X GET "https://app.makeugc.ai/api/platform/templates/list" \
  -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/templates/list", {
  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/templates/list",
    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": {
    "templates": [
      {
        "id": "template_123",
        "title": "Product spotlight",
        "description": "A product demonstration",
        "preview_url": "https://your-cdn.example/reference.mp4",
        "credit": null,
        "category": [
          "Product ads"
        ],
        "require_fields": {
          "product_image": {
            "type": "image",
            "required": true
          },
          "product_name": {
            "type": "input",
            "required": true,
            "max": 100
          }
        }
      }
    ]
  }
}

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

Generate a template video #

POST /templates/generate

Generate with a current app template, a seed and the required inputs declared by that template.

Fetch /templates/list first. Fixed media, model, duration, hook and voice inputs belong at the top level. Other declared require_fields belong inside fields; unknown keys and billing/ownership controls are rejected.

Template-required fields, option lists and per-field length limits are checked at submission. Send product_image or product_images (up to three), not both. For multiple products, the first image satisfies a product_image requirement.

seed is required. Use a safe JSON integer or a signed decimal string for larger values. It selects template variations; it does not guarantee pixel-identical model outputs. Save variation_picks from the response.

Templates are the current app catalog. Older Content Library templates use /content-library/* and cannot be submitted here. Generation cost depends on the model and duration; read credits_used.

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`
`template_id` string Required	template id input. Allowed: `At least 1 characters; Up to 256 characters`
`seed` integer \| string Required	seed input. Allowed: `Minimum -9007199254740991; Maximum 9007199254740991; Up to 64 characters; Pattern: ^-?(0\|[1-9]\d*)$`
`product_image` string Optional	Public HTTP(S) media URL. Private addresses, credentials and data URIs are not accepted.
`product_images` string[] Optional	product images input. Allowed: `At least 1 items; Up to 3 items`
`actor_image` string Optional	Public HTTP(S) media URL. Private addresses, credentials and data URIs are not accepted.
`actor_image_2` string Optional	Public HTTP(S) media URL. Private addresses, credentials and data URIs are not accepted.
`voice_id` string Optional	MakeUGC voice id from GET /video/voices. Allowed: `At least 1 characters; Up to 256 characters`
`model` string Optional	model input. Allowed: `seedance-2.0-fast \| seedance-2.0 \| seedance-2.5` Default: `seedance-2.0-fast`
`duration` string Optional	duration input. Allowed: `10 \| 15 \| 20 \| 25 \| 30` Default: `15`
`aspect_ratio` string Optional	aspect ratio input. Allowed: `9:16 \| 16:9 \| 1:1` Default: `9:16`
`hook` string Optional	hook input. Allowed: `question \| pattern_interrupt \| social_proof \| pov_grab \| whisper_secret \| bold_claim_first`
`fields` object Optional	Only keys declared in the selected template's require_fields. Billing and ownership fields are rejected. Default: `{}`

Request example

cURL

curl --fail-with-body --max-time 120 -X POST "https://app.makeugc.ai/api/platform/templates/generate" \
  -H "X-Api-Key: $MAKEUGC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "project_id": "project_123",
  "template_id": "template_123",
  "seed": 12345,
  "product_image": "https://your-cdn.example/product.jpg",
  "model": "seedance-2.0-fast",
  "duration": "15",
  "aspect_ratio": "9:16",
  "fields": {
    "product_name": "Morning Cup"
  }
}'

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/templates/generate", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "project_id": "project_123",
  "template_id": "template_123",
  "seed": 12345,
  "product_image": "https://your-cdn.example/product.jpg",
  "model": "seedance-2.0-fast",
  "duration": "15",
  "aspect_ratio": "9:16",
  "fields": {
    "product_name": "Morning Cup"
  }
}),
  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",
    "template_id": "template_123",
    "seed": 12345,
    "product_image": "https://your-cdn.example/product.jpg",
    "model": "seedance-2.0-fast",
    "duration": "15",
    "aspect_ratio": "9:16",
    "fields": {
        "product_name": "Morning Cup"
    }
}

response = requests.post(
    "https://app.makeugc.ai/api/platform/templates/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",
    "model": "seedance-2.0-fast",
    "credits_used": 1.5,
    "seed": 12345,
    "variation_picks": {}
  }
}

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

Get template video status #

GET /templates/status

Poll the ID from /templates/generate, scoped to your API key's account.

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/templates/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/templates/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/templates/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.