API Reference

The UnrealUGC API is a JSON-over-HTTPS REST API. Everything you can do in the dashboard — generating videos, browsing creators and voices, managing projects — is available programmatically.

• Base URL: https://unrealugc.com/api/v1
• Auth: Bearer token (see Authentication)
• Content type: application/json
• Versioning: URL-versioned (v1). Breaking changes ship as new versions; v1 stays stable.

Create an API key under Settings → API Keys. Keys start with usk_live_ and are shown once at creation — store yours somewhere safe.

Send the key as a Bearer token on every request:

curl https://unrealugc.com/api/v1/me \
  -H "Authorization: Bearer usk_live_YOUR_KEY_HERE"

API access requires an active subscription or non-zero credit balance — the same paywall as the web dashboard.

Per API key:

• Default: 60 requests / minute
• Generation (POST /v1/videos): 10 requests / minute

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds). Over the limit returns 429 with Retry-After.

Errors use a stable envelope:

{
  "error": {
    "code": "insufficient_credits",
    "message": "280 credits required",
    "details": { "required": 280 }
  }
}

HTTP status codes match the error class:

• 400 — invalid request (bad JSON, missing fields, bad values)
• 401 — missing or invalid API key
• 402 — billing problem (no subscription, no credits)
• 404 — resource not found
• 413 — request body too large
• 429 — rate limit exceeded
• 5xx — server-side issue (retry with backoff)

List endpoints support cursor pagination via limit (max 100) and cursor (the id of the last item from the previous page).

curl "https://unrealugc.com/api/v1/videos?limit=20&cursor=cvxyz..." \
  -H "Authorization: Bearer $UNREALUGC_API_KEY"

List responses include these fields:

• data — array of items
• has_more — boolean, true if more pages remain
• next_cursor — pass as cursor on the next request, or null

Information about the account behind the API key.

GET /v1/me

curl https://unrealugc.com/api/v1/me \
  -H "Authorization: Bearer $UNREALUGC_API_KEY"

{
  "id": "cu1abc...",
  "email": "you@example.com",
  "name": "Your Name",
  "plan": "PRO",
  "subscriptionStatus": "ACTIVE",
  "credits": 4280
}

GET /v1/credits

{
  "credits": 4280,
  "subscriptionCredits": 4000,
  "purchasedCredits": 280
}

The pool of video models you can pick from. Pass the id of a model into generate_video.videoModel.

Response — model object

{
  "object": "list",
  "data": [
    {
      "id": "kling-2.6",
      "name": "Kling 2.6",
      "description": "Cinematic realism with native audio.",
      "maxDurationSeconds": 10,
      "supportsNativeAudio": true,
      "aspectRatios": ["9:16", "16:9", "1:1"],
      "tier": "premium"
    }
  ]
}

Creators are the on-screen personas. UnrealUGC ships with 85+ curated stock creators across age, gender, accent, and vibe — and you can upload your own custom avatars.

GET /v1/creators

Query params: include (stock or custom, default both), limit (max 250).

curl "https://unrealugc.com/api/v1/creators?include=stock" \
  -H "Authorization: Bearer $UNREALUGC_API_KEY"

Stock creator object

Custom creator object

POST /v1/creators

Two-step: first call POST /v1/uploads/avatar and PUT the image. Then finalize:

curl https://unrealugc.com/api/v1/creators \
  -X POST \
  -H "Authorization: Bearer $UNREALUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Founder avatar",
    "r2Key": "custom-creators/.../1234.png"
  }'

Voices for the voiceover. UnrealUGC ships with a curated catalog of stock voices and supports cloning your own from a 2-5 minute audio sample.

Voice object

POST /v1/voices

Two-step like creators. First POST /v1/uploads/voice-sample, PUT the audio, then finalize:

curl https://unrealugc.com/api/v1/voices \
  -X POST \
  -H "Authorization: Bearer $UNREALUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Founder voice",
    "r2Key": "custom-voices/.../1234.mp3",
    "contentType": "audio/mpeg",
    "durationSeconds": 180,
    "gender": "female"
  }'

Stock voice ids are referenced directly from generate_video.voiceId. Custom voice ids are also accepted — we resolve both transparently.

Projects group videos by product or campaign. Optional — if you skipprojectId on a video generation, we create one fromproductName automatically.

Project object

POST /v1/projects

curl https://unrealugc.com/api/v1/projects \
  -X POST \
  -H "Authorization: Bearer $UNREALUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q3 Launch", "productName": "Acme Skincare" }'

The main resource. POST /v1/videos kicks off an async generation; the response returns immediately with the video in GENERATING.

Video object

POST /v1/videos

curl https://unrealugc.com/api/v1/videos \
  -X POST \
  -H "Authorization: Bearer $UNREALUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "creatorId": "tech-savvy-female-30",
    "script": "I have been using this for two weeks and I am genuinely shocked at how good it is.",
    "productName": "Acme Skincare",
    "videoModel": "kling-2.6",
    "useNativeAudio": true,
    "durationSeconds": 10,
    "aspectRatio": "9:16"
  }'

Generation is async. Either poll GET /v1/videos/:id every ~15s, or use webhooks for push updates (recommended).

POST /v1/videos/estimate

Quote the credit cost of a generation before running it. Same input shape as the create endpoint minus the assets.

{
  "totalCredits": 280,
  "credits": 4280,
  "canAfford": true
}

GET /v1/videos

Query params: limit (max 100), status, projectId, cursor.

curl "https://unrealugc.com/api/v1/videos?status=COMPLETED&limit=20" \
  -H "Authorization: Bearer $UNREALUGC_API_KEY"

Custom creator avatars and voice cloning samples use a two-step upload flow. The API returns a presigned URL, you PUT the file directly to it, then finalize by calling POST /v1/creators or POST /v1/voices.

POST /v1/uploads/avatar

{
  "uploadUrl": "https://...",
  "r2Key": "custom-creators/.../1234.png",
  "method": "PUT",
  "headers": { "Content-Type": "image/png" },
  "expiresInSeconds": 600
}

Then PUT your file:

curl "$UPLOAD_URL" -X PUT --upload-file ./avatar.png \
  -H "Content-Type: image/png"

Finally, call POST /v1/creators with the r2Key to finalize the creator. Avatars are limited to 5 MB.

POST /v1/uploads/voice-sample

Same response shape as the avatar endpoint. Voice samples must be 2-5 minutes of clear speech for best results. Max upload size is 25 MB. Then call POST /v1/voices with the r2Key to finalize.

Subscribe to video.created, video.completed, and video.failed at Settings → Webhooks. Each delivery is signed with HMAC-SHA256 and includes a stable delivery id for idempotency.

Full payload shape, signature verification snippets, and retry behavior: Webhooks docs →

• Stock creator ids accept either the internal id or the slug
• Voice ids: stock voice ids and custom voice ids are both accepted by generate_video.voiceId; the API resolves transparently
• Project and video ids are cuids
• API keys start with usk_live_
• Webhook signing secrets start with whsec_

A dedicated SDK is on the way. Until then, the API is plain JSON over HTTPS — any HTTP client works. If you're driving from an LLM agent, use the MCP server instead — it wraps every endpoint as a typed tool. Dedicated guides for popular agents:

• Claude Code (CLI / IDE)
• OpenAI Codex (CLI + Cloud)
• OpenClaw (personal AI agent)
• Hermes Agent (Nous Research)