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. The quote is derived from your script length and the model's valid clip durations, so it matches exactly what POST /v1/videos will charge.

{
  "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)