ClipUGC API reference

Make UGC videos for your app from code. Create AI influencers who keep the same face, animate them into short clips, and turn a clip plus your app screen recording into the video you post.

Base URL: https://clipugc.com/api/v2
Format: JSON in and out. File fields also accept multipart.
OpenAPI spec: https://clipugc.com/docs/api.json. Import it into Postman or Insomnia, or generate a client from it. The URL stays the same between releases.
Access: the Professional and Business plans. See pricing.

Prefer a terminal or an AI assistant? The same features ship as the clipugc CLI and as a connector for Claude and ChatGPT.

Getting started

1. Create a key. In the dashboard open API Keys and press Create API Key. Copy the key right away. It is shown once.

2. Make your first request.

curl https://clipugc.com/api/v2/user \
  -H "Authorization: Bearer $CLIPUGC_API_KEY" \
  -H "Accept: application/json"

3. Create a character. Describe the person in plain words.

curl -X POST https://clipugc.com/api/v2/ai-characters \
  -H "Authorization: Bearer $CLIPUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles"}'

The response holds the character and its first look in data.reference_images, with status: "pending". This costs 2 credits.

4. Poll the look until it is ready.

curl https://clipugc.com/api/v2/character-images/LOOK_ID/check-status \
  -H "Authorization: Bearer $CLIPUGC_API_KEY"

Repeat every 5 to 10 seconds until data.status is completed (or failed, which refunds the credits). The picture is in data.media.image_url.

5. Animate the look into a clip.

curl -X POST https://clipugc.com/api/v2/character-videos/image-to-video \
  -H "Authorization: Bearer $CLIPUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"character_reference_image_id": LOOK_ID, "prompt": "looks at the phone, surprised, then smiles", "duration": "5"}'

Poll GET /character-videos/CLIP_ID/check-status the same way. A 5 second clip costs 7 credits.

6. Upload your app screen recording.

curl -X POST https://clipugc.com/api/v2/uploads/presign \
  -H "Authorization: Bearer $CLIPUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "app_video", "extension": "mp4"}'

# then PUT the raw file to data.upload_url, adding any headers from data.headers
curl --upload-file recording.mp4 "UPLOAD_URL"

7. Make the finished video.

curl -X POST https://clipugc.com/api/v2/character-videos/CLIP_ID/merge \
  -H "Authorization: Bearer $CLIPUGC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app_video_key": "KEY_FROM_STEP_6", "hook_text": "this app saved me 3 hours this week"}'

The response carries data.merged_video_id. Poll GET /merged-videos/MERGED_VIDEO_ID until data.status is completed, then call GET /merged-videos/MERGED_VIDEO_ID/download for a link to the MP4.

Authentication

Send your key as a bearer token on every request:

Authorization: Bearer YOUR_API_KEY

A key acts as your account and spends its credits, so keep it on your server and never ship it in an app. You can create several keys and revoke any of them on the API Keys page.

Keys work while your account is on Professional or Business, including a trial. When the subscription ends, at the end of the paid period, the keys pause. They work again as soon as you subscribe again.

Responses and errors

Every response uses the same JSON envelope:

{
  "statusCode": 200,
  "errorMessage": null,
  "data": { },
  "message": "Success"
}

Read statusCode, not only the HTTP status. Most errors arrive with HTTP 200 and the real code in statusCode, with a readable errorMessage. The exceptions are listed in the HTTP column below.

statusCode	HTTP	Meaning
`200`, `201`	200	Success. `201` means something was created or started.
`400`	200	The request cannot be done, for example nothing to download yet.
`401`	200	Missing, wrong or revoked key.
`403`	200	Not allowed, for example a private character of another account or the monthly character limit.
`403`	403	The account is blocked.
`404`	200	Not found, or not yours.
`500`	200	Something failed on our side. Retry later.
`1002`	402	Your plan does not include API access. `data.pricing_url` links the plans.
`1002`	200	A feature your plan does not include.
`1003`	200	Not enough credits. See `GET /credits` and `GET /credits/packs`.
`429`	429	Rate limit for this key. Wait `data.retry_after` seconds.

Two cases do not use the envelope:

Invalid fields answer HTTP 422 with {"message": "...", "errors": {"field": ["..."]}}.
The finished video limit answers HTTP 429 with {"message": "Too Many Attempts."} and a Retry-After header.

Rate limits

Limits count per key, per minute:

Plan	All requests	Calls that start a generation
Professional	60	10
Business	180	30

Calls that start a generation are: creating a character, generating looks, new looks from a look, animating, motion clips, finished videos and every retry.

Finished videos also have their own limit per account: 3 a minute and 20 a day.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get HTTP 429 with a Retry-After header.

Polling

There are no webhooks yet. Every generation call returns right away with status: "pending" and works in the background. Poll the matching status endpoint until the status is completed or failed:

You created	Poll
A look	`GET /character-images/{id}/check-status`
A clip	`GET /character-videos/{id}/check-status`
A finished video	`GET /merged-videos/{id}`

Statuses go pending, then processing, then completed or failed. Every 5 to 10 seconds is a good pace. Media links in responses are signed and expire, so fetch a fresh one with the download endpoints when you need the file.

Credits

Generations spend credits from your balance. Professional includes 150 credits a month and Business 600. For more, GET /credits/packs lists one-time packs with a checkout_url each. A failed generation refunds its credits by itself.

What	Credits
A look	2
A 5 second clip	7
A 10 second clip	13
A clip with a restyled scene (5 seconds)	9
A motion clip	3 per second of driver video, at most 90
A finished video	free
Hook suggestions	free

Prices can change. GET /credits always returns the current ones, so read them there instead of hard-coding them.

Endpoints

GET /api/v2/ai-characters: List characters
POST /api/v2/ai-characters: Create a character
GET /api/v2/ai-characters/{id}: Get a character
PATCH /api/v2/ai-characters/{id}: Rename or share a character
DELETE /api/v2/ai-characters/{id}: Delete a character
POST /api/v2/ai-characters/{character}/reference-images: Generate looks
GET /api/v2/ai-characters/{character}/reference-images: List a character's looks
GET /api/v2/character-images/{id}: Get a look
DELETE /api/v2/character-images/{id}: Delete a look
GET /api/v2/character-images/{id}/check-status: Check a look's status
POST /api/v2/character-images/{id}/variation: Make a new look from a look
POST /api/v2/character-images/{id}/retry: Retry a failed look
POST /api/v2/character-videos/image-to-video: Animate a look
POST /api/v2/character-videos/{id}/merge: Make a finished video
GET /api/v2/merged-videos: List finished videos
POST /api/v2/merged-videos/{id}/retry: Retry a failed finished video
GET /api/v2/merged-videos/{id}/download: Get a finished video download link
GET /api/v2/merged-videos/{id}: Get a finished video
DELETE /api/v2/merged-videos/{id}: Delete a finished video
POST /api/v2/uploads/presign: Get an upload URL
POST /api/v2/character-videos/hook-suggestions: Suggest hook lines
GET /api/v2/credits: Get your balance and prices
GET /api/v2/character-videos: List clips
POST /api/v2/character-videos/motion-control: Copy a movement onto a look
POST /api/v2/character-videos/{id}/retry: Retry a failed clip
GET /api/v2/character-videos/{id}/download: Get a clip download link
GET /api/v2/character-videos/{id}: Get a clip
DELETE /api/v2/character-videos/{id}: Delete a clip
GET /api/v2/character-videos/{id}/check-status: Check a clip's status
GET /api/v2/user: Get your account
GET /api/v2/credits/transactions: List credit transactions
GET /api/v2/credits/packs: List credit packs