{ "openapi": "3.1.0", "info": { "title": "ClipUGC API", "version": "2", "description": "Make UGC videos for your app from code. Create AI influencers who keep the same face,\nanimate them into short clips, and turn a clip plus your app screen recording into the\nvideo you post.\n\n- **Base URL:** `https:\/\/clipugc.com\/api\/v2`\n- **Format:** JSON in and out. File fields also accept multipart.\n- **OpenAPI spec:** [https:\/\/clipugc.com\/docs\/api.json](https:\/\/clipugc.com\/docs\/api.json). Import it into Postman or Insomnia, or generate\n a client from it. The URL stays the same between releases.\n- **Access:** the Professional and Business plans. See [pricing](https:\/\/clipugc.com\/#pricing).\n\nPrefer a terminal or an AI assistant? The same features ship as the\n[`clipugc` CLI](https:\/\/www.npmjs.com\/package\/clipugc) and as a [connector for Claude and\nChatGPT](https:\/\/clipugc.com\/mcp).\n\n## Getting started\n\n**1. Create a key.** In the dashboard open [API Keys](https:\/\/clipugc.com\/dashboard\/api-keys) and press\n*Create API Key*. Copy the key right away. It is shown once.\n\n**2. Make your first request.**\n\n```bash\ncurl https:\/\/clipugc.com\/api\/v2\/user \\\n -H \"Authorization: Bearer $CLIPUGC_API_KEY\" \\\n -H \"Accept: application\/json\"\n```\n\n**3. Create a character.** Describe the person in plain words.\n\n```bash\ncurl -X POST https:\/\/clipugc.com\/api\/v2\/ai-characters \\\n -H \"Authorization: Bearer $CLIPUGC_API_KEY\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\"description\": \"Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles\"}'\n```\n\nThe response holds the character and its first look in `data.reference_images`, with\n`status: \"pending\"`. This costs 2 credits.\n\n**4. Poll the look until it is ready.**\n\n```bash\ncurl https:\/\/clipugc.com\/api\/v2\/character-images\/LOOK_ID\/check-status \\\n -H \"Authorization: Bearer $CLIPUGC_API_KEY\"\n```\n\nRepeat every 5 to 10 seconds until `data.status` is `completed` (or `failed`, which refunds\nthe credits). The picture is in `data.media.image_url`.\n\n**5. Animate the look into a clip.**\n\n```bash\ncurl -X POST https:\/\/clipugc.com\/api\/v2\/character-videos\/image-to-video \\\n -H \"Authorization: Bearer $CLIPUGC_API_KEY\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\"character_reference_image_id\": LOOK_ID, \"prompt\": \"looks at the phone, surprised, then smiles\", \"duration\": \"5\"}'\n```\n\nPoll `GET \/character-videos\/CLIP_ID\/check-status` the same way. A 5 second clip costs\n7 credits.\n\n**6. Upload your app screen recording.**\n\n```bash\ncurl -X POST https:\/\/clipugc.com\/api\/v2\/uploads\/presign \\\n -H \"Authorization: Bearer $CLIPUGC_API_KEY\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\"purpose\": \"app_video\", \"extension\": \"mp4\"}'\n\n# then PUT the raw file to data.upload_url, adding any headers from data.headers\ncurl --upload-file recording.mp4 \"UPLOAD_URL\"\n```\n\n**7. Make the finished video.**\n\n```bash\ncurl -X POST https:\/\/clipugc.com\/api\/v2\/character-videos\/CLIP_ID\/merge \\\n -H \"Authorization: Bearer $CLIPUGC_API_KEY\" \\\n -H \"Content-Type: application\/json\" \\\n -d '{\"app_video_key\": \"KEY_FROM_STEP_6\", \"hook_text\": \"this app saved me 3 hours this week\"}'\n```\n\nThe response carries `data.merged_video_id`. Poll `GET \/merged-videos\/MERGED_VIDEO_ID` until\n`data.status` is `completed`, then call `GET \/merged-videos\/MERGED_VIDEO_ID\/download` for a\nlink to the MP4.\n\n## Authentication\n\nSend your key as a bearer token on every request:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nA key acts as your account and spends its credits, so keep it on your server and never ship\nit in an app. You can create several keys and revoke any of them on the\n[API Keys](https:\/\/clipugc.com\/dashboard\/api-keys) page.\n\nKeys work while your account is on Professional or Business, including a trial. When the\nsubscription ends, at the end of the paid period, the keys pause. They work again as soon as\nyou subscribe again.\n\n## Responses and errors\n\nEvery response uses the same JSON envelope:\n\n```json\n{\n \"statusCode\": 200,\n \"errorMessage\": null,\n \"data\": { },\n \"message\": \"Success\"\n}\n```\n\n**Read `statusCode`, not only the HTTP status.** Most errors arrive with HTTP 200 and the real\ncode in `statusCode`, with a readable `errorMessage`. The exceptions are listed in the HTTP\ncolumn below.\n\n| statusCode | HTTP | Meaning |\n|---|---|---|\n| `200`, `201` | 200 | Success. `201` means something was created or started. |\n| `400` | 200 | The request cannot be done, for example nothing to download yet. |\n| `401` | 200 | Missing, wrong or revoked key. |\n| `403` | 200 | Not allowed, for example a private character of another account or the monthly character limit. |\n| `403` | 403 | The account is blocked. |\n| `404` | 200 | Not found, or not yours. |\n| `500` | 200 | Something failed on our side. Retry later. |\n| `1002` | 402 | Your plan does not include API access. `data.pricing_url` links the plans. |\n| `1002` | 200 | A feature your plan does not include. |\n| `1003` | 200 | Not enough credits. See `GET \/credits` and `GET \/credits\/packs`. |\n| `429` | 429 | Rate limit for this key. Wait `data.retry_after` seconds. |\n\nTwo cases do not use the envelope:\n\n- **Invalid fields** answer HTTP `422` with `{\"message\": \"...\", \"errors\": {\"field\": [\"...\"]}}`.\n- **The finished video limit** answers HTTP `429` with `{\"message\": \"Too Many Attempts.\"}` and a\n `Retry-After` header.\n\n## Rate limits\n\nLimits count per key, per minute:\n\n| Plan | All requests | Calls that start a generation |\n|---|---|---|\n| Professional | 60 | 10 |\n| Business | 180 | 30 |\n\nCalls that start a generation are: creating a character, generating looks, new looks from a\nlook, animating, motion clips, finished videos and every retry.\n\nFinished videos also have their own limit per account: 3 a minute and\n20 a day.\n\nEvery response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Over the limit you get\nHTTP `429` with a `Retry-After` header.\n\n## Polling\n\nThere are no webhooks yet. Every generation call returns right away with `status: \"pending\"`\nand works in the background. Poll the matching status endpoint until the status is\n`completed` or `failed`:\n\n| You created | Poll |\n|---|---|\n| A look | `GET \/character-images\/{id}\/check-status` |\n| A clip | `GET \/character-videos\/{id}\/check-status` |\n| A finished video | `GET \/merged-videos\/{id}` |\n\nStatuses go `pending`, then `processing`, then `completed` or `failed`. Every 5 to 10 seconds\nis a good pace. Media links in responses are signed and expire, so fetch a fresh one with the\ndownload endpoints when you need the file.\n\n## Credits\n\nGenerations spend credits from your balance. Professional includes\n150 credits a month and Business\n600. For more, `GET \/credits\/packs` lists one-time packs with a\n`checkout_url` each. A failed generation refunds its credits by itself.\n\n| What | Credits |\n|---|---|\n| A look | 2 |\n| A 5 second clip | 7 |\n| A 10 second clip | 13 |\n| A clip with a restyled scene (5 seconds) | 9 |\n| A motion clip | 3 per second of driver video, at most 90 |\n| A finished video | free |\n| Hook suggestions | free |\n\nPrices can change. `GET \/credits` always returns the current ones, so read them there\ninstead of hard-coding them.\n" }, "servers": [ { "url": "https:\/\/clipugc.com\/api\/v2" } ], "tags": [ { "name": "Characters", "description": "AI influencers. Each keeps the same face in every look and clip." }, { "name": "Looks", "description": "Pictures of a character. A look is what a clip animates." }, { "name": "Clips", "description": "Short vertical videos of a character, made from a look." }, { "name": "Finished videos", "description": "The video you post: a clip, your app screen recording and a hook line." }, { "name": "Uploads", "description": "Send large files straight to storage, then pass the key to another endpoint." }, { "name": "Hooks", "description": "Text lines that sit on top of a finished video." }, { "name": "Credits", "description": "Your account, balance, prices and credit packs." } ], "security": [ { "http": [] } ], "paths": { "\/ai-characters": { "get": { "operationId": "v2.ai-characters.index", "description": "Your own characters, the public cast, or both in one feed. Paginated.\n\n`scope=mine` (default) lists your characters. `scope=discover` lists the public cast.\n`scope=feed` lists yours first, then the public cast. A public character your plan does not\nunlock comes back with `is_locked: true` and without a playable `preview_clip.clip_url`.", "summary": "List characters", "tags": [ "Characters" ], "parameters": [ { "name": "search", "in": "query", "description": "Only characters whose name contains this text.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Rows per page, at most 50.", "schema": { "type": "integer", "default": 12 } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "default": 1 } }, { "name": "scope", "in": "query", "description": "mine, discover or feed.", "schema": { "type": "string", "default": "mine" }, "example": "feed" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "ai_characters": [ { "id": 1059, "full_name": "Maya Costa", "display_name": "Maya Costa", "age": null, "gender": null, "nationality": null, "location": null, "vibe": "Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles", "status": "completed", "dna": { "vibe": "Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles", "full_name": "AI Character" }, "visibility": { "is_public": false, "is_featured": false, "is_active": true }, "owner": { "user_id": 19, "is_own": true }, "picture_count": 1, "video_count": 0, "is_locked": false, "cover_image": { "id": 1152, "thumbnail_url": "https:\/\/clipugc.com\/storage\/ai_characters\/reference_images\/character_1152_1790796585_JbKpl.png?..." }, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:49.000000Z" } ], "pagination": { "current_page": 1, "last_page": 1, "per_page": 2, "total": 1, "has_more_pages": false } }, "message": "Success" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "ai_characters": { "type": "array", "items": { "allOf": [ { "$ref": "#\/components\/schemas\/Character" }, { "type": "object", "required": [ "cover_image" ] } ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more_pages": { "type": "boolean" } }, "required": [ "current_page", "last_page", "per_page", "total", "has_more_pages" ] } }, "required": [ "ai_characters", "pagination" ] }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } }, "post": { "operationId": "v2.ai-characters.store", "description": "Describe a person in plain words. ClipUGC designs them and starts their first look, a 9:16\nportrait at 2K.\n\nSend `description` (10 to 1000 characters). Optional: `scene_prompt` (up to 600 characters)\nfor where the first look is set, up to 6 `inspiration_images` (multipart, 8 MB each) and\n`is_public`. The first look comes back in `data.reference_images` with status `pending`.\nPoll `GET \/character-images\/{id}\/check-status` until it is `completed`.\n\nAdd `make_video=true` to also queue a 5 second clip of that first look, with an optional\n`motion_prompt` (up to 1500 characters). The clip starts by itself once the look is ready and\ncomes back in `data.character_video`.\n\nThe structured fields (`full_name`, `age`, face and hair details) are an advanced alternative\nto `description`.\n\n**Credits:** 2 for the first look, or 9 with `make_video`,\ncharged up front.\n\n**Plan limit:** Professional creates 3 characters a\nmonth, Business 10. Using the public cast is not limited.\n\n**Errors:** `1003` not enough credits. `403` monthly limit reached. HTTP `422` invalid fields.", "summary": "Create a character", "tags": [ "Characters" ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/CreateCharacter" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 201, "errorMessage": null, "data": { "id": 1059, "full_name": null, "display_name": "AI Influencer #1059", "age": null, "gender": null, "nationality": null, "location": null, "vibe": null, "status": "completed", "dna": null, "visibility": { "is_public": false, "is_featured": null, "is_active": null }, "owner": { "user_id": 19, "is_own": true }, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:40.000000Z", "reference_images": [ { "id": 1152, "ai_character_id": 1059, "is_owned": true, "shot_type": "frontal", "angle_degrees": 0, "prompt_template": "model_digitals", "scene_prompt": null, "aspect_ratio": "9:16", "resolution": "2K", "status": "processing", "media": { "image_url": null, "thumbnail_url": null, "has_image": false, "width": null, "height": null }, "is_ready_for_use": false, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:40.000000Z" } ], "character_video": null }, "message": "AI character created" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 500 }, "errorMessage": { "type": "string", "const": "Failed to create AI character" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 201 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Character" }, "message": { "type": "string", "const": "AI character created" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Failed to start generation" ] } ] }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Videos of your own AI influencer need a paid plan." ] } ] }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1003 }, "errorMessage": { "type": "string", "const": "Not enough credits to generate reference images" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1003 }, "errorMessage": { "type": "string", "const": "Not enough credits: an influencer with a first video costs 9 credits" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "const": "Your free AI influencer is already designed. A paid plan lets you design more and make videos of them." }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 403 }, "errorMessage": { "type": "string" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/ai-characters\/{id}": { "get": { "operationId": "v2.ai-characters.show", "description": "One character with its counts and a preview clip. Yours, or any public one.\n\n**Errors:** `404` not found. `403` a private character of another account.", "summary": "Get a character", "tags": [ "Characters" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1059, "full_name": "AI Character", "display_name": "AI Character", "age": null, "gender": null, "nationality": null, "location": null, "vibe": "Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles", "status": "completed", "dna": { "vibe": "Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles", "full_name": "AI Character" }, "visibility": { "is_public": false, "is_featured": false, "is_active": true }, "owner": { "user_id": 19, "is_own": true }, "reference_image_count": 1, "picture_count": 1, "video_count": 0, "is_locked": false, "preview_clip": null, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:41.000000Z" }, "message": "Success" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Character" }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 403 }, "errorMessage": { "type": "string", "const": "Access denied to this AI character" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "AI character not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } }, "patch": { "operationId": "v2.ai-characters.update", "description": "Change `full_name` (2 to 120 characters) or `is_public`. Owner only.\n\n**Errors:** `404` not found or not yours. HTTP `422` invalid fields.", "summary": "Rename or share a character", "tags": [ "Characters" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/UpdateCharacter" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1059, "full_name": "Maya Costa", "display_name": "Maya Costa", "age": null, "gender": null, "nationality": null, "location": null, "vibe": "Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles", "status": "completed", "dna": { "vibe": "Maya, 26, a friendly barista from Lisbon with curly dark hair and freckles", "full_name": "AI Character" }, "visibility": { "is_public": false, "is_featured": false, "is_active": true }, "owner": { "user_id": 19, "is_own": true }, "reference_image_count": 1, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:49.000000Z" }, "message": "AI character updated" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Character" }, "message": { "type": "string", "const": "AI character updated" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "AI character not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } }, "delete": { "operationId": "v2.ai-characters.destroy", "description": "Deletes the character with all of its looks, clips and files. Owner only. This cannot be undone.\n\n**Errors:** `404` not found or not yours.", "summary": "Delete a character", "tags": [ "Characters" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": null, "message": "AI character deleted" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "null" }, "message": { "type": "string", "const": "AI character deleted" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "AI character not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/ai-characters\/{character}\/reference-images": { "post": { "operationId": "v2.ai-characters.reference-images.generate", "description": "New pictures of the same face, one per entry in `shot_types`: `frontal` (default),\n`three_quarter`, `profile` or `back`.\n\nOptional: `scene_prompt` (up to 600 characters) for the setting and outfit, `template`\n(`model_digitals`, `scene_recreation` or `specific_angle`; picked for you when omitted),\n`aspect_ratio` (default `9:16`), `resolution` (`0.5K`, `1K`, `2K` or `4K`, default `2K`) and\nup to 6 `inspiration_images` (multipart, 8 MB each).\n\nWorks on your own characters and on any public one. The new looks are yours. They come back\nwith status `pending`: poll `GET \/character-images\/{id}\/check-status`.\n\n**Credits:** 2 per look.\n\n**Errors:** `1003` not enough credits. `404` character not found. `403` a public character\nyour plan does not unlock. HTTP `422` invalid fields.", "summary": "Generate looks", "tags": [ "Looks" ], "parameters": [ { "name": "character", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/GenerateLooks" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 201, "errorMessage": null, "data": [ { "id": 1153, "ai_character_id": 1059, "is_owned": true, "shot_type": "three_quarter", "angle_degrees": 45, "prompt_template": "scene_recreation", "scene_prompt": "behind the counter of a small coffee shop, morning light", "aspect_ratio": "9:16", "resolution": "2K", "status": "processing", "media": { "image_url": null, "thumbnail_url": null, "has_image": false, "width": null, "height": null }, "is_ready_for_use": false, "created_at": "2026-09-30T19:29:50.000000Z", "updated_at": "2026-09-30T19:29:50.000000Z" } ], "message": "Reference image generation started" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 500 }, "errorMessage": { "type": "string", "const": "Failed to generate reference images" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 201 }, "errorMessage": { "type": "null" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Look" } }, "message": { "type": "string", "const": "Reference image generation started" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Failed to start generation" ] } ] }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1003 }, "errorMessage": { "type": "string", "const": "Not enough credits to generate reference images" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 403 }, "errorMessage": { "type": "string", "const": "Upgrade your plan to contribute to this influencer" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "AI character not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } }, "get": { "operationId": "v2.ai-characters.reference-images.index", "description": "On your own character: your looks that have not failed. On a public character: every\ncompleted look from anyone, plus your own that are still in progress.\n\n**Errors:** `404` character not found. `403` a private character of another account.", "summary": "List a character's looks", "tags": [ "Looks" ], "parameters": [ { "name": "character", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": [ { "id": 1154, "ai_character_id": 1059, "is_owned": true, "shot_type": "frontal", "angle_degrees": 0, "prompt_template": "scene_recreation", "scene_prompt": "at the beach at sunset, white linen shirt", "aspect_ratio": "9:16", "resolution": "2K", "status": "processing", "media": { "image_url": null, "thumbnail_url": null, "has_image": false, "width": null, "height": null }, "is_ready_for_use": false, "created_at": "2026-09-30T19:29:51.000000Z", "updated_at": "2026-09-30T19:29:51.000000Z" }, { "id": 1153, "ai_character_id": 1059, "is_owned": true, "shot_type": "three_quarter", "angle_degrees": 45, "prompt_template": "scene_recreation", "scene_prompt": "behind the counter of a small coffee shop, morning light", "aspect_ratio": "9:16", "resolution": "2K", "status": "processing", "media": { "image_url": null, "thumbnail_url": null, "has_image": false, "width": null, "height": null }, "is_ready_for_use": false, "created_at": "2026-09-30T19:29:50.000000Z", "updated_at": "2026-09-30T19:29:50.000000Z" }, { "id": 1152, "ai_character_id": 1059, "is_owned": true, "shot_type": "frontal", "angle_degrees": 0, "prompt_template": "model_digitals", "scene_prompt": null, "aspect_ratio": "9:16", "resolution": "2K", "status": "completed", "media": { "image_url": "https:\/\/clipugc.com\/storage\/ai_characters\/reference_images\/character_1152_1790796585_JbKpl.png?...", "thumbnail_url": "https:\/\/clipugc.com\/storage\/ai_characters\/reference_images\/character_1152_1790796585_JbKpl.png?...", "has_image": true, "width": 768, "height": 1344 }, "is_ready_for_use": true, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:47.000000Z" } ], "message": "Success" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Look" } }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 403 }, "errorMessage": { "type": "string", "const": "Access denied" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "AI character not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-images\/{id}": { "get": { "operationId": "v2.character-images.show", "description": "One look. Yours, or a look of a public character.\n\n**Errors:** `404` not found. `403` not visible to you.", "summary": "Get a look", "tags": [ "Looks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1152, "ai_character_id": 1059, "is_owned": true, "shot_type": "frontal", "angle_degrees": 0, "prompt_template": "model_digitals", "scene_prompt": null, "aspect_ratio": "9:16", "resolution": "2K", "status": "completed", "media": { "image_url": "https:\/\/clipugc.com\/storage\/ai_characters\/reference_images\/character_1152_1790796585_JbKpl.png?...", "thumbnail_url": "https:\/\/clipugc.com\/storage\/ai_characters\/reference_images\/character_1152_1790796585_JbKpl.png?...", "has_image": true, "width": 768, "height": 1344 }, "is_ready_for_use": true, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:47.000000Z" }, "message": "Success" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Look" }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 403 }, "errorMessage": { "type": "string", "const": "Access denied" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Reference image not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } }, "delete": { "operationId": "v2.character-images.destroy", "description": "Deletes one of your looks and its file.\n\n**Errors:** `404` not found or not yours.", "summary": "Delete a look", "tags": [ "Looks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": null, "message": "Reference image deleted" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "null" }, "message": { "type": "string", "const": "Reference image deleted" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Reference image not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-images\/{id}\/check-status": { "get": { "operationId": "v2.character-images.check-status", "description": "Poll this after creating a look until `status` is `completed` or `failed`. Every 5 to 10\nseconds is enough. When it is `completed`, `media.image_url` holds the picture. Your own looks only.\n\n**Errors:** `404` not found or not yours.", "summary": "Check a look's status", "tags": [ "Looks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1152, "ai_character_id": 1059, "is_owned": true, "shot_type": "frontal", "angle_degrees": 0, "prompt_template": "model_digitals", "scene_prompt": null, "aspect_ratio": "9:16", "resolution": "2K", "status": "completed", "media": { "image_url": "https:\/\/clipugc.com\/storage\/ai_characters\/reference_images\/character_1152_1790796585_JbKpl.png?...", "thumbnail_url": "https:\/\/clipugc.com\/storage\/ai_characters\/reference_images\/character_1152_1790796585_JbKpl.png?...", "has_image": true, "width": 768, "height": 1344 }, "is_ready_for_use": true, "created_at": "2026-09-30T19:29:40.000000Z", "updated_at": "2026-09-30T19:29:47.000000Z" }, "message": "Status check completed" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Look" }, "message": { "type": "string", "const": "Status check completed" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Reference image not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-images\/{id}\/variation": { "post": { "operationId": "v2.character-images.variation", "description": "The same face in a new scene or outfit. `scene_prompt` (3 to 600 characters) says what changes.\n`count` makes 1 to 4 looks at once.\n\nOr set `before_after=true` and describe a change in `scene_prompt`, for example\n\"3 months of gym\". You get two looks, before and after.\n\nWorks on your looks and on looks of public characters. The new looks are yours.\n\n**Credits:** 2 per look, so a before and after pair costs 4.\n\n**Errors:** `1003` not enough credits. `404` look not found. `403` a public character your plan\ndoes not unlock. HTTP `422` invalid fields.", "summary": "Make a new look from a look", "tags": [ "Looks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/NewLookFromLook" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 201, "errorMessage": null, "data": [ { "id": 1154, "ai_character_id": 1059, "is_owned": true, "shot_type": "frontal", "angle_degrees": 0, "prompt_template": "scene_recreation", "scene_prompt": "at the beach at sunset, white linen shirt", "aspect_ratio": "9:16", "resolution": "2K", "status": "processing", "media": { "image_url": null, "thumbnail_url": null, "has_image": false, "width": null, "height": null }, "is_ready_for_use": false, "created_at": "2026-09-30T19:29:51.000000Z", "updated_at": "2026-09-30T19:29:51.000000Z" } ], "message": "Variation(s) started" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 201 }, "errorMessage": { "type": "null" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Look" } }, "message": { "type": "string", "enum": [ "Before & after pair started", "Variation(s) started" ] } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Could not create the look" ] } ] }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1003 }, "errorMessage": { "type": "string" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 403 }, "errorMessage": { "type": "string", "const": "Upgrade your plan to contribute to this influencer" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Reference image not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-images\/{id}\/retry": { "post": { "operationId": "v2.character-images.retry", "description": "Starts a failed look again. A failure refunds its credits, so a retry charges again.\n\n**Credits:** 2.\n\n**Errors:** `404` not found or not yours. `400` the look has not failed, or not enough credits.", "summary": "Retry a failed look", "tags": [ "Looks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1153, "ai_character_id": 1059, "is_owned": true, "shot_type": "three_quarter", "angle_degrees": 45, "prompt_template": "scene_recreation", "scene_prompt": "behind the counter of a small coffee shop, morning light", "aspect_ratio": "9:16", "resolution": "2K", "status": "processing", "media": { "image_url": null, "thumbnail_url": null, "has_image": false, "width": null, "height": null }, "is_ready_for_use": false, "created_at": "2026-09-30T19:29:50.000000Z", "updated_at": "2026-09-30T19:31:47.000000Z" }, "message": "Retrying generation" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Look" }, "message": { "type": "string", "const": "Retrying generation" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "This image cannot be retried" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Reference image not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/image-to-video": { "post": { "operationId": "v2.character-videos.image-to-video", "description": "Turns a look into a short vertical clip.\n\nSource, one of: `character_reference_image_id`, a look of yours or of a public character, or\n`source_image_key`, your own photo sent through [Uploads](#\/operations\/v2.uploads.presign) with\npurpose `photo`.\n\nOptional: `prompt` (up to 1500 characters) for motion and expression, `duration` of `5`\n(default) or `10` seconds, and `scene_prompt` (up to 600 characters) to restyle the setting\nbefore animating.\n\nThe clip comes back with status `pending`. Poll `GET \/character-videos\/{id}\/check-status`\nuntil it is `completed`.\n\n**Credits:** 7 for 5 seconds, 13 for 10 seconds. A `scene_prompt`\nadds 2 for the restyled look.\n\n**Errors:** `1003` not enough credits. `404` look not found. `400` uploaded photo not found.\nHTTP `422` invalid fields.", "summary": "Animate a look", "tags": [ "Clips" ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/CreateClip" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 201, "errorMessage": null, "data": { "id": 1112, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "image_to_video", "status": "pending", "prompt": "looks at the phone, surprised, then smiles", "duration": "5", "aspect_ratio": "9:16", "merged_video_id": null, "media": { "clip_url": null, "preview_url": null, "clip_thumbnail_url": null, "has_clip": false }, "is_ready_for_use": false, "created_at": "2026-09-30T19:29:52.000000Z", "updated_at": "2026-09-30T19:29:52.000000Z" }, "message": "Video generation started" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 500 }, "errorMessage": { "type": "string", "const": "Failed to generate video" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 201 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Clip" }, "message": { "type": "string", "const": "Video generation started" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1003 }, "errorMessage": { "type": "string", "const": "Not enough credits to generate a clip" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Reference image not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "Uploaded photo not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "A reference (driver) video is required for motion control" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/{id}\/merge": { "post": { "operationId": "v2.character-videos.merge", "description": "Plays your app screen recording after a clip, with a hook line on top. This is the video you\npost.\n\nSend `hook_text` (up to 150 characters) and the recording, either as `app_video` (multipart mp4\nor mov, up to 100 MB) or as `app_video_key` from [Uploads](#\/operations\/v2.uploads.presign) with\npurpose `app_video`. Optional background music: `music` (mp3, wav or m4a) or `music_key`.\n\nWorks on your completed clips and on completed clips of public characters. The response is\nthe clip, now carrying `merged_video_id`. Poll `GET \/merged-videos\/{merged_video_id}` until\nits `status` is `completed`, then download it.\n\n**Credits:** free. Rendering runs on our servers, so this call has its own limit:\n3 a minute and 20 a day per account.\n\n**Errors:** `404` clip not found or not usable. `400` no app recording. HTTP `422` invalid\nfields. HTTP `429` too many finished videos.", "summary": "Make a finished video", "tags": [ "Finished videos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/CreateFinishedVideo" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 201, "errorMessage": null, "data": { "id": 1112, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "image_to_video", "status": "completed", "prompt": "looks at the phone, surprised, then smiles", "duration": "5", "aspect_ratio": "9:16", "merged_video_id": 18, "media": { "clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "preview_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "clip_thumbnail_url": null, "has_clip": true }, "is_ready_for_use": true, "created_at": "2026-09-30T19:29:52.000000Z", "updated_at": "2026-09-30T19:29:59.000000Z" }, "message": "Merge started" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 500 }, "errorMessage": { "type": "string", "const": "Failed to merge video" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 201 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Clip" }, "message": { "type": "string", "const": "Merge started" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Merge failed" ] } ] }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "An app-demo video is required" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Character video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/merged-videos": { "get": { "operationId": "v2.merged-videos.index", "description": "Your finished videos, newest first. They are private to you, even when the clip came from a\npublic character.", "summary": "List finished videos", "tags": [ "Finished videos" ], "parameters": [ { "name": "status", "in": "query", "description": "pending, processing, completed or failed.", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Rows per page, at most 50.", "schema": { "type": "integer", "default": 12 } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "merged_videos": [ { "id": 18, "uuid": "6b40524f-4820-41d6-92e7-0bd7477d6014", "character_video_id": 1112, "ai_character_id": 1059, "status": "completed", "hook_text": "this app saved me 3 hours this week", "has_watermark": false, "credits_charged": 0, "can_retry": false, "media": { "merged_url": "https:\/\/clipugc.com\/storage\/ai_characters\/merged\/UGC_5L1ANwHTPwo6GdqkppzE.mp4?...", "merged_thumbnail_url": "https:\/\/clipugc.com\/storage\/ai_characters\/merged_thumbnails\/thumb_Nhb7fU6k2FKnAuEyjwU4.jpg?...", "has_merged": true, "source_clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?..." }, "created_at": "2026-09-30T19:30:04.000000Z", "updated_at": "2026-09-30T19:31:14.000000Z" } ], "pagination": { "current_page": 1, "last_page": 1, "per_page": 2, "total": 1, "has_more_pages": false } }, "message": "Success" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "merged_videos": { "type": "array", "items": { "$ref": "#\/components\/schemas\/FinishedVideo" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more_pages": { "type": "boolean" } }, "required": [ "current_page", "last_page", "per_page", "total", "has_more_pages" ] } }, "required": [ "merged_videos", "pagination" ] }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/merged-videos\/{id}\/retry": { "post": { "operationId": "v2.merged-videos.retry", "description": "Renders a failed finished video again. Only possible while `can_retry` is true: the app\nrecording was sent as an upload key and that upload still exists (uploads are kept 48 hours).\n\n**Credits:** free.\n\n**Errors:** `404` not found or not yours. `400` cannot be retried. HTTP `429` too many\nfinished videos.", "summary": "Retry a failed finished video", "tags": [ "Finished videos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 18, "uuid": "6b40524f-4820-41d6-92e7-0bd7477d6014", "character_video_id": 1112, "ai_character_id": 1059, "status": "pending", "hook_text": "this app saved me 3 hours this week", "has_watermark": false, "credits_charged": 0, "can_retry": false, "media": { "merged_url": null, "merged_thumbnail_url": null, "has_merged": false, "source_clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?..." }, "created_at": "2026-09-30T19:30:04.000000Z", "updated_at": "2026-09-30T19:31:10.000000Z" }, "message": "Retrying merge" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/FinishedVideo" }, "message": { "type": "string", "const": "Retrying merge" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "This ad cannot be retried" ] } ] }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Merged video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/merged-videos\/{id}\/download": { "get": { "operationId": "v2.merged-videos.download", "description": "A signed MP4 link that works for 30 minutes.\n\n**Errors:** `404` not found or not yours. `400` not finished yet.", "summary": "Get a finished video download link", "tags": [ "Finished videos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "download_url": "https:\/\/clipugc.com\/storage\/ai_characters\/merged\/UGC_5L1ANwHTPwo6GdqkppzE.mp4?..." }, "message": "Download URL created" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "download_url": { "type": "string" } }, "required": [ "download_url" ] }, "message": { "type": "string", "const": "Download URL created" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "This video has nothing to download yet" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Merged video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/merged-videos\/{id}": { "get": { "operationId": "v2.merged-videos.show", "description": "Poll this after [making a finished video](#\/operations\/v2.character-videos.merge) until `status` is\n`completed` or `failed`. Every 10 seconds is enough.\n\n**Errors:** `404` not found or not yours.", "summary": "Get a finished video", "tags": [ "Finished videos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 18, "uuid": "6b40524f-4820-41d6-92e7-0bd7477d6014", "character_video_id": 1112, "ai_character_id": 1059, "status": "completed", "hook_text": "this app saved me 3 hours this week", "has_watermark": false, "credits_charged": 0, "can_retry": false, "media": { "merged_url": "https:\/\/clipugc.com\/storage\/ai_characters\/merged\/UGC_5L1ANwHTPwo6GdqkppzE.mp4?...", "merged_thumbnail_url": "https:\/\/clipugc.com\/storage\/ai_characters\/merged_thumbnails\/thumb_Nhb7fU6k2FKnAuEyjwU4.jpg?...", "has_merged": true, "source_clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?..." }, "created_at": "2026-09-30T19:30:04.000000Z", "updated_at": "2026-09-30T19:31:14.000000Z" }, "message": "Success" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/FinishedVideo" }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Merged video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } }, "delete": { "operationId": "v2.merged-videos.destroy", "description": "Deletes the finished video and its file. The clip it came from is not touched.\n\n**Errors:** `404` not found or not yours.", "summary": "Delete a finished video", "tags": [ "Finished videos" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": null, "message": "Merged video deleted" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "null" }, "message": { "type": "string", "const": "Merged video deleted" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Merged video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/uploads\/presign": { "post": { "operationId": "v2.uploads.presign", "description": "Send large files (anything over 2 MB) this way instead of as multipart.\n\n1. Call this with `purpose` and the file `extension`.\n2. `PUT` the raw file bytes to `upload_url`, with the returned `headers`, within 30 minutes.\n3. Pass `key` to the endpoint that needs the file, for example `app_video_key`.\n\n| purpose | extensions | used by |\n|---|---|---|\n| `photo` | png, jpg, jpeg, webp | `source_image_key` |\n| `driver_video` | mp4, mov | `reference_video_key` |\n| `app_video` | mp4, mov | `app_video_key` |\n| `music` | mp3, wav, m4a | `music_key` |\n\nUploaded files are deleted after 48 hours.\n\n**Errors:** `400` unknown purpose or extension.", "summary": "Get an upload URL", "tags": [ "Uploads" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "driver_video", "app_video", "music", "photo" ] }, "extension": { "type": "string", "maxLength": 5 } }, "required": [ "purpose", "extension" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "key": "tmp\/api-uploads\/19\/app_video\/c7588b43-7833-4124-b92d-7a9d08f934c5.mp4", "upload_url": "https:\/\/clipugc.com\/storage\/tmp\/api-uploads\/19\/app_video\/c7588b43-7833-4124-b92d-7a9d08f934c5.mp4?...", "method": "PUT", "headers": [], "expires_at": "2026-09-30T20:00:03+00:00" }, "message": "Upload URL created" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "upload_url": { "type": "string" }, "method": { "type": "string", "const": "PUT" }, "headers": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "expires_at": { "type": "string" } }, "required": [ "key", "upload_url", "method", "headers", "expires_at" ] }, { "type": "object", "properties": { "key": { "type": "string" }, "upload_url": { "type": "string" }, "method": { "type": "string", "const": "PUT" }, "headers": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "expires_at": { "type": "string" } }, "required": [ "key", "upload_url", "method", "headers", "expires_at" ] } ] }, "message": { "type": "string", "const": "Upload URL created" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/hook-suggestions": { "post": { "operationId": "v2.character-videos.hook-suggestions", "description": "Short text lines for the top of a finished video, written for app promotion. Pass `context`\n(your app, your audience, the vibe) for more specific lines.\n\n**Credits:** free.", "summary": "Suggest hook lines", "tags": [ "Hooks" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "context": { "type": "string", "examples": [ "A budgeting app for students" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "hooks": [ "nobody talks about this student budget hack", "POV: you stop stressing over student spending", "i wasn't going to share my secret budgeting app", "stop scrolling if you ever went broke before payday", "this kept my bank account alive till finals" ] }, "message": "Hook suggestions" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "hooks": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "string", "const": "same person btw" }, { "type": "string", "const": "i was today years old when i found this app" }, { "type": "string", "const": "nobody talks about this app and it shows" }, { "type": "string", "const": "this app did all of that for me" }, { "type": "string", "const": "watch till the end, worth it" } ], "minItems": 5, "maxItems": 5 }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "hooks" ] }, "message": { "type": "string", "const": "Hook suggestions" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/credits": { "get": { "operationId": "v2.credits.index", "description": "Your credit balance and what each generation costs right now. Prices are set by the server,\nso read them here rather than hard-coding them.", "summary": "Get your balance and prices", "tags": [ "Credits" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "balance": 200, "costs": { "image": 2, "clip": 7, "clip_10s": 13, "motion_per_second": 3, "scene_staged": 9, "merge": 0, "story_scene": 13, "story_scene_hd": 20 } }, "message": "Credits retrieved successfully" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "balance": { "type": "integer" }, "costs": { "type": "object", "properties": { "image": { "type": "integer", "const": 2 }, "clip": { "type": "integer", "const": 7 }, "clip_10s": { "type": "integer", "const": 13 }, "motion_per_second": { "type": "integer", "const": 3 }, "scene_staged": { "type": "integer", "const": 9 }, "merge": { "type": "integer" }, "story_scene": { "type": "integer", "const": 13 }, "story_scene_hd": { "type": "integer", "const": 20 } }, "required": [ "image", "clip", "clip_10s", "motion_per_second", "scene_staged", "merge", "story_scene", "story_scene_hd" ] } }, "required": [ "balance", "costs" ] }, "message": { "type": "string", "const": "Credits retrieved successfully" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos": { "get": { "operationId": "v2.character-videos.index", "description": "Your clips, newest first. Failed clips are never listed.\n\n`ai_character_id` limits the list to one character. On a public character that shows every\ncompleted clip from anyone, plus your own in progress. `mergeable=1` lists the clips you can\nmake a finished video from: your completed clips, then the public cast's.", "summary": "List clips", "tags": [ "Clips" ], "parameters": [ { "name": "ai_character_id", "in": "query", "description": "Only clips of this character.", "schema": { "type": "integer" } }, { "name": "mergeable", "in": "query", "description": "Set to 1 for clips ready for a finished video.", "schema": { "type": "boolean" } }, { "name": "per_page", "in": "query", "description": "Rows per page, at most 50.", "schema": { "type": "integer", "default": 12 } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "character_videos": [ { "id": 1113, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "motion_control", "status": "processing", "prompt": "Animate the uploaded reference image into a realistic vertical phone-camera clip. subtle natural movement, breathing, occasional blinking, slight body and phone-camera motion. Keep the exact same person, face, body proportions, outfit, framing and lighting. Natural blinking, subtle breathing, realistic skin texture, stable proportions, no face distortion, no body distortion, no extra fingers, no unnatural hands.", "duration": null, "aspect_ratio": "9:16", "merged_video_id": null, "ai_character": { "id": 1059, "display_name": "Maya Costa" }, "media": { "clip_url": null, "preview_url": null, "clip_thumbnail_url": null, "has_clip": false }, "is_ready_for_use": false, "created_at": "2026-09-30T19:30:12.000000Z", "updated_at": "2026-09-30T19:30:13.000000Z" }, { "id": 1112, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "image_to_video", "status": "completed", "prompt": "looks at the phone, surprised, then smiles", "duration": "5", "aspect_ratio": "9:16", "merged_video_id": 18, "ai_character": { "id": 1059, "display_name": "Maya Costa" }, "media": { "clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "preview_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "clip_thumbnail_url": null, "has_clip": true }, "is_ready_for_use": true, "created_at": "2026-09-30T19:29:52.000000Z", "updated_at": "2026-09-30T19:29:59.000000Z" } ], "pagination": { "current_page": 1, "last_page": 1, "per_page": 2, "total": 2, "has_more_pages": false } }, "message": "Success" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "character_videos": { "type": "array", "items": { "$ref": "#\/components\/schemas\/Clip" } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more_pages": { "type": "boolean" } }, "required": [ "current_page", "last_page", "per_page", "total", "has_more_pages" ] } }, "required": [ "character_videos", "pagination" ] }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/motion-control": { "post": { "operationId": "v2.character-videos.motion-control", "description": "Makes a clip where the character repeats the movement of a driver video you send.\n\nSend `character_reference_image_id` (or `source_image_key`) plus the driver video, either as\n`reference_video` (multipart mp4 or mov, up to 50 MB) or as `reference_video_key` from\n[Uploads](#\/operations\/v2.uploads.presign) with purpose `driver_video`. The clip is as long as the\ndriver, up to 30 seconds. Set `keep_original_sound=true` to keep the\ndriver's audio.\n\n**Credits:** 3 per driver second, rounded up, at most\n90.\n\n**Errors:** `1003` not enough credits. `400` no driver video. `404` look not found.\nHTTP `422` invalid fields.", "summary": "Copy a movement onto a look", "tags": [ "Clips" ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/CreateClip" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 201, "errorMessage": null, "data": { "id": 1113, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "motion_control", "status": "pending", "prompt": null, "duration": null, "aspect_ratio": "9:16", "merged_video_id": null, "media": { "clip_url": null, "preview_url": null, "clip_thumbnail_url": null, "has_clip": false }, "is_ready_for_use": false, "created_at": "2026-09-30T19:30:12.000000Z", "updated_at": "2026-09-30T19:30:12.000000Z" }, "message": "Video generation started" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 500 }, "errorMessage": { "type": "string", "const": "Failed to generate video" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 201 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Clip" }, "message": { "type": "string", "const": "Video generation started" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1003 }, "errorMessage": { "type": "string", "const": "Not enough credits to generate a clip" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Reference image not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "Uploaded photo not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "A reference (driver) video is required for motion control" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/{id}\/retry": { "post": { "operationId": "v2.character-videos.retry", "description": "Starts a failed clip again. A failure refunds its credits, so a retry charges the same amount\nagain.\n\n**Credits:** what the clip cost the first time.\n\n**Errors:** `404` not found or not yours. `400` the clip has not failed, or not enough credits.", "summary": "Retry a failed clip", "tags": [ "Clips" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1114, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "image_to_video", "status": "pending", "prompt": "waves at the camera", "duration": "5", "aspect_ratio": "9:16", "merged_video_id": null, "media": { "clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1114_1790796699_lbwWR.mp4?...", "preview_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1114_1790796699_lbwWR.mp4?...", "clip_thumbnail_url": null, "has_clip": true }, "is_ready_for_use": false, "created_at": "2026-09-30T19:31:38.000000Z", "updated_at": "2026-09-30T19:31:48.000000Z" }, "message": "Retrying generation" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Clip" }, "message": { "type": "string", "const": "Retrying generation" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "This video cannot be retried" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Character video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/{id}\/download": { "get": { "operationId": "v2.character-videos.download", "description": "A signed MP4 link that works for 30 minutes. Once you have a completed finished video made\nfrom this clip, the link is for that finished video instead of the raw clip.\n\n**Errors:** `404` not found or not yours. `400` nothing to download yet.", "summary": "Get a clip download link", "tags": [ "Clips" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "download_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?..." }, "message": "Download URL created" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "download_url": { "type": "string" } }, "required": [ "download_url" ] }, "message": { "type": "string", "const": "Download URL created" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 400 }, "errorMessage": { "type": "string", "const": "This video has nothing to download yet" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Character video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/{id}": { "get": { "operationId": "v2.character-videos.show", "description": "One of your clips.\n\n**Errors:** `404` not found or not yours.", "summary": "Get a clip", "tags": [ "Clips" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1112, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "image_to_video", "status": "completed", "prompt": "looks at the phone, surprised, then smiles", "duration": "5", "aspect_ratio": "9:16", "merged_video_id": 18, "media": { "clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "preview_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "clip_thumbnail_url": null, "has_clip": true }, "is_ready_for_use": true, "created_at": "2026-09-30T19:29:52.000000Z", "updated_at": "2026-09-30T19:29:59.000000Z" }, "message": "Success" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Clip" }, "message": { "type": "string", "const": "Success" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Character video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } }, "delete": { "operationId": "v2.character-videos.destroy", "description": "Deletes one of your clips and its files. Finished videos made from it are kept.\n\n**Errors:** `404` not found or not yours.", "summary": "Delete a clip", "tags": [ "Clips" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": null, "message": "Character video deleted" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "null" }, "message": { "type": "string", "const": "Character video deleted" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Character video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/character-videos\/{id}\/check-status": { "get": { "operationId": "v2.character-videos.check-status", "description": "Poll this after creating a clip until `status` is `completed` or `failed`. Every 10 seconds is\nenough. When it is `completed`, `media.clip_url` holds the video.\n\n**Errors:** `404` not found or not yours.", "summary": "Check a clip's status", "tags": [ "Clips" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 1112, "ai_character_id": 1059, "character_reference_image_id": 1152, "is_owned": true, "mode": "image_to_video", "status": "completed", "prompt": "looks at the phone, surprised, then smiles", "duration": "5", "aspect_ratio": "9:16", "merged_video_id": null, "media": { "clip_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "preview_url": "https:\/\/clipugc.com\/storage\/ai_characters\/clips\/character_clip_1112_1790796597_SfRE1.mp4?...", "clip_thumbnail_url": null, "has_clip": true }, "is_ready_for_use": true, "created_at": "2026-09-30T19:29:52.000000Z", "updated_at": "2026-09-30T19:29:59.000000Z" }, "message": "Status check completed" } ], "anyOf": [ { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Clip" }, "message": { "type": "string", "const": "Status check completed" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] }, { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 404 }, "errorMessage": { "type": "string", "const": "Character video not found" }, "data": { "type": "null" }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/user": { "get": { "operationId": "v2.user.index", "description": "The account the API key belongs to and its plan. Your balance is `credits.general_credits`.\nThe other `credits` fields count usage of the older product and can be ignored.", "summary": "Get your account", "tags": [ "Credits" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "id": 19, "name": "Your Name", "email": "you@example.com", "email_verified_at": null, "created_at": "2026-09-30T19:27:25.000000Z", "subscription": { "is_subscribed": true, "is_trialing": false, "active_subscription": { "uuid": "e5a2c21b-7315-41f3-96be-c3b7589b6c21", "status": "active", "ends_at": "2027-09-30 19:27:25" }, "plan_name": "Professional Monthly" }, "credits": { "general_credits": 200, "video_credits_used": 0, "video_credits_limit": 0, "video_credits_remaining": 0, "video_generation_cost": 1, "ai_model_credits_used": 0, "ai_model_credits_limit": 15, "ai_model_credits_remaining": 15, "ai_model_generation_cost": 5, "has_enough_video_credits": true, "has_enough_ai_model_credits": true }, "permissions": { "can_generate_ai_influencer": true, "visible_ai_influencer_count": -1, "should_add_watermark": false } }, "message": "User info is retrieved successfully" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "$ref": "#\/components\/schemas\/Account" }, "message": { "type": "string", "const": "User info is retrieved successfully" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/credits\/transactions": { "get": { "operationId": "v2.credits.transactions", "description": "Every credit added or spent, newest first. Paginated.", "summary": "List credit transactions", "tags": [ "Credits" ], "parameters": [ { "name": "per_page", "in": "query", "description": "Rows per page, at most 50.", "schema": { "type": "integer", "default": 12 } }, { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "transactions": [ { "id": 119, "uuid": "0048583a-74e9-4d52-b96b-91c7be2a77b1", "type": "deduction", "action": "character_clip_generation", "amount": -90, "balance_after": 97, "description": "AI Character video clip generation (90 credits)", "created_at": "2026-09-30T19:30:12+00:00" }, { "id": 118, "uuid": "9185c66f-8def-4325-8e5e-d14c2cb0da23", "type": "deduction", "action": "character_clip_generation", "amount": -7, "balance_after": 187, "description": "AI Character video clip generation (7 credits)", "created_at": "2026-09-30T19:29:52+00:00" }, { "id": 117, "uuid": "273ca375-6cc6-45f1-b75e-af133bf308bc", "type": "deduction", "action": "character_image_generation", "amount": -2, "balance_after": 194, "description": "AI Character reference image generation", "created_at": "2026-09-30T19:29:51+00:00" } ], "pagination": { "current_page": 1, "last_page": 2, "per_page": 3, "total": 6, "has_more_pages": true } }, "message": "Credit transactions retrieved successfully" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "type": { "type": "string" }, "action": { "type": "string" }, "amount": { "type": "integer" }, "balance_after": { "type": "integer" }, "description": { "type": "string" }, "created_at": { "type": [ "string", "null" ] } }, "required": [ "id", "uuid", "type", "action", "amount", "balance_after", "description", "created_at" ] } }, "pagination": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more_pages": { "type": "boolean" } }, "required": [ "current_page", "last_page", "per_page", "total", "has_more_pages" ] } }, "required": [ "transactions", "pagination" ] }, "message": { "type": "string", "const": "Credit transactions retrieved successfully" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } }, "\/credits\/packs": { "get": { "operationId": "v2.credits.packs", "description": "One-time credit packs you can buy. `checkout_url` opens the web checkout.", "summary": "List credit packs", "tags": [ "Credits" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "examples": [ { "statusCode": 200, "errorMessage": null, "data": { "packs": [ { "slug": "starter-pack", "name": "Starter Pack", "credits": 50, "revenuecat_product_id": "credits_pack_50", "checkout_url": "https:\/\/clipugc.com\/buy\/product\/starter-pack", "prices": [ { "amount": 999, "currency": "USD" } ] }, { "slug": "creator-pack", "name": "Creator Pack", "credits": 150, "revenuecat_product_id": "credits_pack_150", "checkout_url": "https:\/\/clipugc.com\/buy\/product\/creator-pack", "prices": [ { "amount": 2499, "currency": "USD" } ] }, { "slug": "studio-pack", "name": "Studio Pack", "credits": 400, "revenuecat_product_id": "credits_pack_400", "checkout_url": "https:\/\/clipugc.com\/buy\/product\/studio-pack", "prices": [ { "amount": 5999, "currency": "USD" } ] } ] }, "message": "Credit packs retrieved successfully" } ], "properties": { "statusCode": { "type": "integer", "const": 200 }, "errorMessage": { "type": "null" }, "data": { "type": "object", "properties": { "packs": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "credits": { "type": "integer" }, "revenuecat_product_id": { "type": [ "string", "null" ] }, "checkout_url": { "type": "string" }, "prices": { "type": "array", "items": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "amount", "currency" ] } } }, "required": [ "slug", "name", "credits", "revenuecat_product_id", "checkout_url", "prices" ] } } }, "required": [ "packs" ] }, "message": { "type": "string", "const": "Credit packs retrieved successfully" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "402": { "description": "Your plan does not include API access (app code 1002).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 1002 }, "errorMessage": { "type": "string", "examples": [ "API keys need the Professional or Business plan. Upgrade at https:\/\/clipugc.com\/#pricing" ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } }, "429": { "description": "Rate limit for this API key. Wait `data.retry_after` seconds (also in the Retry-After header).", "content": { "application\/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "const": 429 }, "errorMessage": { "type": "string", "examples": [ "Too many requests for this API key: 60 per minute. Retry after 42 seconds." ] }, "data": { "type": "object", "description": "Details, such as pricing_url or retry_after." }, "message": { "type": "null" } }, "required": [ "statusCode", "errorMessage", "data", "message" ] } } } } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "Your API key from Dashboard, API Keys. Needs the Professional or Business plan.", "scheme": "bearer" } }, "schemas": { "Account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "email_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "subscription": { "type": "object", "properties": { "is_subscribed": { "type": "boolean" }, "is_trialing": { "type": "boolean" }, "active_subscription": { "type": [ "object", "null" ], "properties": { "uuid": { "type": "string" }, "status": { "type": "string" }, "ends_at": { "type": "string" } }, "required": [ "uuid", "status", "ends_at" ] }, "plan_name": { "type": [ "string", "null" ], "description": "Your current plan." } }, "required": [ "is_subscribed", "is_trialing", "active_subscription", "plan_name" ] }, "credits": { "type": "object", "properties": { "general_credits": { "type": "integer", "description": "Your credit balance." }, "video_credits_used": { "type": "integer" }, "video_credits_limit": { "type": "integer" }, "video_credits_remaining": { "type": "integer" }, "video_generation_cost": { "type": "integer", "const": 1 }, "ai_model_credits_used": { "type": "integer" }, "ai_model_credits_limit": { "type": "integer" }, "ai_model_credits_remaining": { "type": "integer" }, "ai_model_generation_cost": { "type": "integer", "const": 5 }, "has_enough_video_credits": { "type": "boolean" }, "has_enough_ai_model_credits": { "type": "boolean" } }, "required": [ "general_credits", "video_credits_used", "video_credits_limit", "video_credits_remaining", "video_generation_cost", "ai_model_credits_used", "ai_model_credits_limit", "ai_model_credits_remaining", "ai_model_generation_cost", "has_enough_video_credits", "has_enough_ai_model_credits" ] }, "permissions": { "type": "object", "properties": { "can_generate_ai_influencer": { "type": "boolean" }, "visible_ai_influencer_count": { "type": "integer" }, "should_add_watermark": { "type": "boolean" } }, "required": [ "can_generate_ai_influencer", "visible_ai_influencer_count", "should_add_watermark" ] } }, "required": [ "id", "name", "email", "email_verified_at", "created_at", "subscription", "credits", "permissions" ], "title": "Account" }, "Character": { "type": "object", "properties": { "id": { "type": "integer" }, "full_name": { "type": [ "string", "null" ] }, "display_name": { "type": "string", "description": "The name to show: `full_name`, or \"AI Influencer #id\" when it has none." }, "age": { "type": [ "integer", "null" ] }, "gender": { "type": [ "string", "null" ] }, "nationality": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "vibe": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "pending, processing, completed or failed." }, "dna": { "type": [ "object", "null" ], "description": "The structured appearance that keeps the face the same. Null until the first look is designed.", "additionalProperties": {} }, "visibility": { "type": "object", "properties": { "is_public": { "type": "boolean", "description": "Shared in the public cast." }, "is_featured": { "type": [ "boolean", "null" ] }, "is_active": { "type": [ "boolean", "null" ] } }, "required": [ "is_public", "is_featured", "is_active" ] }, "owner": { "type": "object", "properties": { "user_id": { "type": [ "integer", "null" ] }, "is_own": { "type": "boolean", "description": "True when the character is yours." } }, "required": [ "user_id", "is_own" ] }, "reference_image_count": { "type": "integer" }, "picture_count": { "type": "integer", "description": "Completed looks." }, "video_count": { "type": "integer", "description": "Clips you can see. On a public character that counts every completed clip." }, "is_locked": { "type": "boolean", "description": "A public character your plan does not unlock. Its playable clip URLs are withheld." }, "cover_image": { "type": [ "object", "null" ], "description": "The cover look as a small thumbnail.", "properties": { "id": { "type": "integer" }, "thumbnail_url": { "type": [ "string", "null" ] } }, "required": [ "id", "thumbnail_url" ] }, "preview_clip": { "type": [ "object", "null" ], "description": "A clip to preview the character with: your newest, else the owner's. `clip_url` is null when locked.", "properties": { "id": { "type": "string" }, "clip_url": { "type": [ "string", "null" ] }, "preview_url": { "type": [ "string", "null" ] }, "clip_thumbnail_url": { "type": [ "string", "null" ] } }, "required": [ "id", "clip_url", "preview_url", "clip_thumbnail_url" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "reference_images": { "type": "array", "description": "Only when creating: the first look, still pending.", "items": { "$ref": "#\/components\/schemas\/Look" } }, "character_video": { "description": "Only when creating with `make_video`: the queued clip.", "anyOf": [ { "$ref": "#\/components\/schemas\/Clip" }, { "type": "null" } ] } }, "required": [ "id", "full_name", "display_name", "age", "gender", "nationality", "location", "vibe", "status", "dna", "visibility", "owner", "created_at", "updated_at" ], "title": "Character" }, "Clip": { "type": "object", "properties": { "id": { "type": "integer" }, "ai_character_id": { "type": [ "integer", "null" ] }, "character_reference_image_id": { "type": [ "integer", "null" ] }, "is_owned": { "type": "boolean", "description": "True when you created this clip. Only your own clips can be retried or deleted." }, "mode": { "type": [ "string", "null" ], "description": "image_to_video or motion_control." }, "status": { "type": [ "string", "null" ], "description": "pending, processing, completed or failed." }, "prompt": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ], "description": "Length in seconds. Motion clips follow the driver video." }, "aspect_ratio": { "type": [ "string", "null" ] }, "merged_video_id": { "type": [ "integer", "null" ], "description": "Your newest finished video made from this clip, if any. Follow it at `GET \/merged-videos\/{id}`." }, "ai_character": { "type": [ "object", "null" ], "description": "The character's id and display name.", "properties": { "id": { "type": "integer" }, "display_name": { "type": "string" } }, "required": [ "id", "display_name" ] }, "media": { "type": "object", "properties": { "clip_url": { "type": [ "string", "null" ], "description": "The full-quality MP4, for downloading. Signed and expires." }, "preview_url": { "type": [ "string", "null" ], "description": "A small MP4 for playback. Signed and expires." }, "clip_thumbnail_url": { "type": [ "string", "null" ], "description": "A still frame of the clip." }, "has_clip": { "type": "boolean" } }, "required": [ "clip_url", "preview_url", "clip_thumbnail_url", "has_clip" ] }, "is_ready_for_use": { "type": "boolean", "description": "Completed and has a video, so it can become a finished video." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "ai_character_id", "character_reference_image_id", "is_owned", "mode", "status", "prompt", "duration", "aspect_ratio", "merged_video_id", "media", "is_ready_for_use", "created_at", "updated_at" ], "title": "Clip" }, "CreateCharacter": { "type": "object", "properties": { "description": { "type": "string", "description": "Who the character is, in plain words. 10 to 1000 characters.", "minLength": 10, "maxLength": 1000 }, "scene_prompt": { "type": [ "string", "null" ], "description": "Where the first look is set. Up to 600 characters.", "maxLength": 600 }, "make_video": { "type": [ "boolean", "null" ], "description": "Also queue a 5 second clip of the first look." }, "motion_prompt": { "type": [ "string", "null" ], "description": "How the character moves in that clip. Up to 1500 characters.", "maxLength": 1500 }, "inspiration_images": { "type": [ "array", "null" ], "description": "Photos that guide the look. Up to 6, 8 MB each, multipart.", "items": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Maximum file size: 8192 kilobytes." }, "maxItems": 6 }, "full_name": { "type": "string", "description": "Advanced: the structured path instead of `description`.", "minLength": 2, "maxLength": 120 }, "age": { "type": [ "integer", "null" ], "minimum": 18, "maximum": 99 }, "gender": { "type": [ "string", "null" ], "maxLength": 255 }, "nationality": { "type": [ "string", "null" ], "maxLength": 255 }, "location": { "type": [ "string", "null" ], "maxLength": 255 }, "vibe": { "type": [ "string", "null" ], "maxLength": 255 }, "height": { "type": [ "string", "null" ], "maxLength": 255 }, "weight": { "type": [ "string", "null" ], "maxLength": 255 }, "bust": { "type": [ "string", "null" ], "maxLength": 255 }, "waist": { "type": [ "string", "null" ], "maxLength": 255 }, "hips": { "type": [ "string", "null" ], "maxLength": 255 }, "body_type": { "type": [ "string", "null" ], "maxLength": 255 }, "head_to_body_ratio": { "type": [ "string", "null" ], "maxLength": 255 }, "face_shape": { "type": [ "string", "null" ], "maxLength": 255 }, "eye_color": { "type": [ "string", "null" ], "maxLength": 255 }, "eye_shape": { "type": [ "string", "null" ], "maxLength": 255 }, "eye_spacing": { "type": [ "string", "null" ], "maxLength": 255 }, "eyebrow_shape": { "type": [ "string", "null" ], "maxLength": 255 }, "eyebrow_thickness": { "type": [ "string", "null" ], "maxLength": 255 }, "nose_bridge": { "type": [ "string", "null" ], "maxLength": 255 }, "nose_tip": { "type": [ "string", "null" ], "maxLength": 255 }, "nose_width": { "type": [ "string", "null" ], "maxLength": 255 }, "lip_color": { "type": [ "string", "null" ], "maxLength": 255 }, "lip_volume": { "type": [ "string", "null" ], "maxLength": 255 }, "lip_ratio": { "type": [ "string", "null" ], "maxLength": 255 }, "jaw_shape": { "type": [ "string", "null" ], "maxLength": 255 }, "jaw_definition": { "type": [ "string", "null" ], "maxLength": 255 }, "skin_tone": { "type": [ "string", "null" ], "maxLength": 255 }, "skin_undertone": { "type": [ "string", "null" ], "maxLength": 255 }, "skin_texture": { "type": [ "string", "null" ], "maxLength": 255 }, "freckles": { "type": [ "string", "null" ], "maxLength": 255 }, "moles": { "type": [ "string", "null" ], "maxLength": 1000 }, "scars": { "type": [ "string", "null" ], "maxLength": 1000 }, "birthmarks": { "type": [ "string", "null" ], "maxLength": 1000 }, "hair_color": { "type": [ "string", "null" ], "maxLength": 255 }, "hair_texture": { "type": [ "string", "null" ], "maxLength": 255 }, "hair_length": { "type": [ "string", "null" ], "maxLength": 255 }, "hair_thickness": { "type": [ "string", "null" ], "maxLength": 255 }, "hair_parting": { "type": [ "string", "null" ], "maxLength": 255 }, "default_style": { "type": [ "string", "null" ], "maxLength": 255 }, "is_public": { "type": [ "boolean", "null" ], "description": "Share the character in the public cast." } }, "title": "CreateCharacter" }, "CreateClip": { "type": "object", "properties": { "character_reference_image_id": { "type": "integer", "description": "The look to animate. Yours, or a look of a public character." }, "source_image_key": { "type": "string", "description": "Or your own photo: an upload key with purpose photo." }, "prompt": { "type": [ "string", "null" ], "description": "Motion and expression. Up to 1500 characters.", "maxLength": 1500 }, "scene_prompt": { "type": [ "string", "null" ], "description": "Restyle the setting before animating. Image to video only, adds the cost of a look.", "maxLength": 600 }, "duration": { "type": [ "string", "null" ], "description": "5 or 10 seconds. Image to video only.", "enum": [ "5", "10", null ] }, "keep_original_sound": { "type": "boolean", "description": "Keep the driver video's audio. Motion clips only." }, "reference_video": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "description": "The driver video: multipart mp4 or mov, up to 50 MB." }, "reference_video_key": { "type": [ "string", "null" ], "description": "Or an upload key with purpose driver_video." } }, "title": "CreateClip" }, "CreateFinishedVideo": { "type": "object", "properties": { "app_video": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Your app screen recording: multipart mp4 or mov, up to 100 MB." }, "app_video_key": { "type": "string", "description": "Or an upload key with purpose app_video." }, "hook_text": { "type": "string", "description": "The line shown on top. Up to 150 characters.", "maxLength": 150 }, "music": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Background music: multipart mp3, wav or m4a." }, "music_key": { "type": [ "string", "null" ], "description": "Or an upload key with purpose music." } }, "required": [ "hook_text" ], "title": "CreateFinishedVideo" }, "FinishedVideo": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "character_video_id": { "type": [ "integer", "null" ], "description": "The clip it was made from. Null once that clip is deleted." }, "ai_character_id": { "type": [ "integer", "null" ] }, "status": { "type": "string", "description": "pending, processing, completed or failed." }, "hook_text": { "type": [ "string", "null" ], "description": "The line shown on top of the video." }, "has_watermark": { "type": "boolean", "description": "True when the video carries the ClipUGC watermark." }, "credits_charged": { "type": "integer", "description": "Credits this video cost." }, "can_retry": { "type": "boolean", "description": "A failed video can be rendered again without sending the recording again." }, "media": { "type": "object", "properties": { "merged_url": { "type": [ "string", "null" ], "description": "The finished MP4. Signed and expires." }, "merged_thumbnail_url": { "type": [ "string", "null" ], "description": "A still frame of the finished video." }, "has_merged": { "type": "boolean" }, "source_clip_url": { "type": [ "string", "null" ], "description": "The clip it was made from." } }, "required": [ "merged_url", "merged_thumbnail_url", "has_merged", "source_clip_url" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "uuid", "character_video_id", "ai_character_id", "status", "hook_text", "has_watermark", "credits_charged", "can_retry", "media", "created_at", "updated_at" ], "title": "FinishedVideo" }, "GenerateLooks": { "type": "object", "properties": { "shot_types": { "type": [ "array", "null" ], "description": "One look per entry. Default: frontal.", "items": { "type": "string", "enum": [ "frontal", "three_quarter", "profile", "back" ] }, "minItems": 1 }, "template": { "type": [ "string", "null" ], "description": "Framing. Picked for you when omitted: scene_recreation with a scene_prompt, else model_digitals.", "enum": [ "model_digitals", "scene_recreation", "specific_angle", null ] }, "scene_prompt": { "type": [ "string", "null" ], "description": "Setting and outfit. Up to 600 characters.", "maxLength": 600 }, "aspect_ratio": { "type": [ "string", "null" ], "description": "Default 9:16." }, "resolution": { "type": [ "string", "null" ], "description": "Default 2K.", "enum": [ "0.5K", "1K", "2K", "4K", null ] }, "inspiration_images": { "type": [ "array", "null" ], "description": "Photos that guide the look. Up to 6, 8 MB each, multipart.", "items": { "type": "string", "format": "binary", "contentMediaType": "application\/octet-stream", "description": "Maximum file size: 8192 kilobytes." }, "maxItems": 6 } }, "title": "GenerateLooks" }, "Look": { "type": "object", "properties": { "id": { "type": "integer" }, "ai_character_id": { "type": [ "integer", "null" ] }, "is_owned": { "type": "boolean", "description": "True when you created this look. Only your own looks can be retried or deleted." }, "shot_type": { "type": [ "string", "null" ], "description": "frontal, three_quarter, profile or back." }, "angle_degrees": { "type": [ "integer", "null" ] }, "prompt_template": { "type": [ "string", "null" ] }, "scene_prompt": { "type": [ "string", "null" ] }, "aspect_ratio": { "type": [ "string", "null" ] }, "resolution": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "pending, processing, completed or failed." }, "media": { "type": "object", "properties": { "image_url": { "type": [ "string", "null" ], "description": "The full-resolution PNG. Signed and expires." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "A small JPEG for lists and previews. Signed and expires." }, "has_image": { "type": "boolean" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } }, "required": [ "image_url", "thumbnail_url", "has_image", "width", "height" ] }, "is_ready_for_use": { "type": "boolean", "description": "Completed and has a picture, so it can be animated." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "ai_character_id", "is_owned", "shot_type", "angle_degrees", "prompt_template", "scene_prompt", "aspect_ratio", "resolution", "status", "media", "is_ready_for_use", "created_at", "updated_at" ], "title": "Look" }, "NewLookFromLook": { "type": "object", "properties": { "scene_prompt": { "type": "string", "description": "What changes. With before_after, the change over time, for example \"3 months of gym\".", "minLength": 3, "maxLength": 600 }, "count": { "type": "integer", "description": "How many looks, 1 to 4. Ignored with before_after.", "minimum": 1, "maximum": 4 }, "before_after": { "type": "boolean", "description": "Make a before and after pair." } }, "required": [ "scene_prompt" ], "title": "NewLookFromLook" }, "UpdateCharacter": { "type": "object", "properties": { "full_name": { "type": "string", "description": "The new name. 2 to 120 characters.", "minLength": 2, "maxLength": 120 }, "is_public": { "type": "boolean", "description": "Share the character in the public cast, or stop sharing it." } }, "title": "UpdateCharacter" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }