RawUGC API

Procedural knowledge for agents to call the RawUGC API. All requests require an API key from the RawUGC dashboard, passed via environment variable.

Authentication

Environment variable: Read the API key from RAWUGC_API_KEY. The key is created in the RawUGC dashboard and must be kept secret; do not hardcode or log it.
Header: Send on every request: Authorization: Bearer <value of RAWUGC_API_KEY>.
If RAWUGC_API_KEY is missing or empty, inform the user they must set it and obtain a key from the RawUGC dashboard.

Base URL

Production: https://rawugc.com/api/v1
All paths below are relative to this base.

API Versioning

RawUGC uses date-based API versioning. The current latest version is 2026-03-06.

RawUGC-Version request header: Override the version per-request (recommended).
API key pinned version: Set when creating the key in the dashboard.
Fallback: Latest version (2026-03-06) if neither is set.

Always send RawUGC-Version: 2026-03-06 in requests to ensure consistent behavior.

Video Generation

POST /videos/generate

Initiate video generation.

Request body (JSON):

Field	Type	Required	Description
`model`	string	Yes	`sora-2-text-to-video`, `sora-2-image-to-video`, `kling-2.6/motion-control`, `veo3`, `veo3_fast`
`prompt`	string	For text-to-video / veo3	Text description (1-5000 chars)
`imageUrls`	string[]	For image-to-video / kling	URLs, max 10. Veo3/veo3_fast accept up to 2 optional images.
`videoUrls`	string[]	For kling	URLs, max 1. Required for `kling-2.6/motion-control`
`aspectRatio`	string	No	Sora: `portrait`/`landscape`. Veo3: `16:9`/`9:16`/`Auto`
`nFrames`	string	No	`"10"` or `"15"` (Sora only)
`selectedCharacter`	string	No	Character username (e.g. `rawugc.mia`)
`characterOrientation`	string	No	`image` or `video` (kling only)
`mode`	string	No	`720p` or `1080p` (kling only)

Response (201): videoId, model, status, creditsUsed, newBalance, estimatedCompletionTime, createdAt.

GET /videos/:videoId

Get video status. Returns videoId, status, model, prompt, creditsUsed, url (when completed), createdAt, completedAt, failCode, failMessage, versions (edit history array).

GET /videos

List videos. Query: status, limit (1-100, default 50), page. Returns videos array + pagination.

POST /videos/captions

Add styled captions to a completed video. Costs 1 credit.

Field	Type	Required	Description
`videoId`	string	Yes	Video identifier (vid_xxx)
`language`	string	No	Language code (e.g. `en`). Defaults to auto-detect

Response (200): videoId, url, version, operation, creditsUsed.

POST /videos/overlay

Add text overlay to a completed video.

Field	Type	Required	Description
`videoId`	string	Yes	Video identifier (vid_xxx)
`text`	string	Yes	Overlay text (1-500 chars)
`position`	string	No	`top`, `center`, or `bottom`
`fontSize`	integer	No	8-200 pixels
`topBottomMargin`	integer	No	0-500 pixels
`strokeThickness`	number	No	0-10

Response (200): videoId, url, version, operation, creditsUsed.

Image Generation

POST /images/generate

Generate AI images using Nano Banana models. Async -- poll GET /images/:imageId.

Field	Type	Required	Description
`model`	string	Yes	`nano-banana-2` (text-to-image, 4 credits) or `google/nano-banana-edit` (image editing, 2 credits)
`prompt`	string	Yes	Text description or edit instruction (1-20000 chars)
`imageUrls`	string[]	For editing	Source images. Required for `google/nano-banana-edit`. Optional for `nano-banana-2` (reference images, max 14).
`aspectRatio`	string	No	For `nano-banana-2`: `1:1`, `16:9`, `9:16`, `auto`, etc.
`imageSize`	string	No	For `google/nano-banana-edit`: `1:1`, `16:9`, `9:16`, `auto`, etc.
`resolution`	string	No	For `nano-banana-2`: `1K`, `2K`, `4K`
`outputFormat`	string	No	`png`, `jpeg`, `jpg`
`googleSearch`	boolean	No	Use Google Web Search grounding (`nano-banana-2` only)

Response (201): imageId, model, status, creditsUsed, newBalance, estimatedCompletionTime, createdAt.

GET /images/:imageId

Get image status. Returns imageId, status, model, prompt, url (when completed), imageSize, resolution, outputFormat, creditsUsed, createdAt, completedAt, failCode, failMessage.

GET /images

List images. Query: status, limit (1-100, default 20), page. Returns images array + pagination.

Music Generation

POST /music/generate

Generate AI music using Suno models. 3 credits per generation. Async -- poll GET /music/:musicId.

Field	Type	Required	Description
`prompt`	string	Yes	Music description (1-2000 chars)
`model`	string	No	`V3_5`, `V4`, `V4_5`, `V4_5PLUS`, `V4_5ALL`, `V5` (default: `V5`)
`instrumental`	boolean	No	Instrumental only, no vocals (default: true)
`title`	string	No	Track title (max 200 chars). Enables custom mode with `style`.
`style`	string	No	Style descriptor (max 500 chars, e.g. `lo-fi hip hop`)

Response (201): musicId, model, status, creditsUsed, newBalance, estimatedCompletionTime, createdAt.

GET /music/:musicId

Get music status. Returns musicId, status, model, prompt, audioUrl (when completed), albumArtUrl, duration, title, creditsUsed, createdAt, completedAt, failCode, failMessage.

GET /music

List music tracks. Query: status, limit (1-100, default 20), page. Returns tracks array + pagination.

Upload

POST /upload

Upload a video or image file. Returns a URL for use in generation requests (imageUrls, videoUrls) or analyze-video. Max 100MB.

Request: multipart/form-data with file field. Accepted types: video/mp4, video/quicktime, video/webm, image/png, image/jpeg, image/webp.

Response (200): url, contentType, size.

Characters

GET /characters

List all available AI characters (built-in + custom). Returns characters array, count, adminCount, userCount.

GET /characters/:characterId

Get a character by ID. Returns _id, username, displayName, description, videoPreviewUrl, type (admin/user), isActive, createdAt, updatedAt.

Personas (CRUD)

Personas define target audiences for content plan generation.

GET /personas -- List all. Returns personas array + count.
POST /personas -- Create. Body: name (required, max 200), description (required, max 5000). Returns id.
GET /personas/:personaId -- Get one.
PATCH /personas/:personaId -- Update. Body: name, description (both optional).
DELETE /personas/:personaId -- Delete.

PersonaResponse: _id, organizationId, name, description, createdAt, updatedAt.

Messaging (CRUD)

Brand/positioning messaging templates.

GET /messaging -- List all. Returns messages array + count.
POST /messaging -- Create. Body: name (required, max 200), body (required, max 5000). Returns id.
GET /messaging/:messageId -- Get one.
PATCH /messaging/:messageId -- Update. Body: name, body (both optional).
DELETE /messaging/:messageId -- Delete.

MessagingResponse: _id, organizationId, name, body, createdAt, updatedAt.

Products (CRUD)

Products for video generation.

GET /products -- List all. Returns products array + count.
POST /products -- Create. Body: name (required, max 200), photos (required, URL array), description (max 1000), messaging (max 5000). Returns id.
GET /products/:productId -- Get one.
PATCH /products/:productId -- Update. Body: name, description, photos, messaging (all optional).
DELETE /products/:productId -- Delete.

ProductResponse: _id, name, description, photos, messaging, createdAt, updatedAt.

Styles (CRUD)

Video/image creative styles with optional prompt templates.

GET /styles -- List all (built-in + custom). Query: type (video/image). Returns styles array + count.
POST /styles -- Create. Body: name (required, max 200), description (max 1000), type (video/image), aspectRatio (portrait/landscape/square), promptTemplate (max 5000, supports {productName}, {messaging}, {character} placeholders). Returns id.
GET /styles/:styleId -- Get one.
PATCH /styles/:styleId -- Update. All fields optional.
DELETE /styles/:styleId -- Delete.

StyleResponse: _id, name, description, type, aspectRatio, styleId, promptTemplate, isAdmin, isStandard.

Social Scheduling

GET /social/accounts

List connected social accounts (max 3 per org). Returns accounts array + count. Each account: accountId, platform (tiktok/instagram/youtube), username, displayName, profilePicture, isActive.

POST /social/accounts

Sync connected accounts from the scheduling provider. Returns { success: boolean }.

DELETE /social/accounts/:accountId

Disconnect a social account. Returns { success: boolean }.

POST /social/posts

Schedule, draft, or immediately publish a video to social media.

Field	Type	Required	Description
`videoUrl`	string	Yes	URL of video to post
`accountIds`	string[]	Yes	Target account IDs
`mode`	string	Yes	`schedule`, `draft`, or `now`
`scheduledFor`	integer	For schedule	Unix timestamp (ms)
`timezone`	string	No	IANA timezone (default: `UTC`)
`content`	string	No	Caption (max 2200 chars)
`videoId`	string	No	RawUGC video ID to link
`publishToInbox`	boolean	No	Send to TikTok Creator Inbox
`tiktokPrivacyLevel`	string	No	`SELF_ONLY`, `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`
`tiktokAllowComment`	boolean	No	Allow TikTok comments
`tiktokAllowDuet`	boolean	No	Allow TikTok duets
`tiktokAllowStitch`	boolean	No	Allow TikTok stitches
`tiktokCommercialContentType`	string	No	`none`, `brand_organic`, `brand_content`

Response (201): SocialPost object.

GET /social/posts

List posts. Query: fromDate (ms), toDate (ms), includeDrafts (boolean). Returns posts array + count.

GET /social/posts/:postId

Get a post.

PATCH /social/posts/:postId

Update a post. Body: content, scheduledFor, timezone, accountIds (at least one field required).

DELETE /social/posts/:postId

Delete a post. Returns { success: boolean }.

POST /social/posts/:postId/reschedule

Reschedule a post. Body: scheduledFor (required, ms), timezone.

POST /social/posts/:postId/publish

Immediately publish a draft post.

SocialPost: postId, platforms, status (draft/scheduled/published/failed), scheduledFor, timezone, content, videoUrl, createdAt, publishedAt.

Viral Library

GET /viral-library/videos/:videoId

Get a viral library video with full AI analysis (hooks, keyframes, performance insights). Returns ViralLibraryVideo.

GET /viral-library/search

Semantic search across analyzed videos. Query: q (required, natural language), limit (1-50, default 20). Returns results (array of { video, score }), query, total.

Research

POST /scrape-tiktok

Scrape TikTok videos. Costs 3 credits.

Field	Type	Required	Description
`query`	string	Yes	Search keyword, hashtag, or query (max 500)
`mode`	string	No	`keyword`, `hashtag`, `search` (default: `keyword`)
`limit`	integer	No	1-10 (default: 10)

Response (200): scrapeId (use with content-plans), count, videos (array with id, url, author, description, stats, duration, hashtags, thumbnail, videoUrl).

POST /content-plans

Generate a content plan from scraped videos. Costs 3 credits.

Field	Type	Required	Description
`scrapeId`	string	Yes	From scrape-tiktok response
`brief`	string	Yes	Content plan goals (max 5000)

Response (200): planId, scrapeId, brief, topWins, gapsToTest, blueprints (array with category, strategy, evidence, contentIdeas).

GET /content-plans

List all content plans. Returns plans array + count.

POST /analyze-video

Analyze any video URL (social links or direct URLs). Costs 1 credit. Max 150MB.

Field	Type	Required	Description
`videoUrl`	string	Yes	Video URL to analyze
`prompt`	string	No	Custom analysis prompt (max 5000)

Response (200): summary, hook, keyframes (array with timestamp, type, description, visual, audio, text), durationSeconds, tags, whyItPerformed, attributesToCopy, hooksToTest.

Errors

All error responses use RFC 7807 Problem Details (JSON): type, title, status, detail, instance, errors.

Status	Meaning
400	Validation error. Surface `detail` and `errors` to user.
401	Auth error. Check `RAWUGC_API_KEY`.
402	Insufficient credits. Add credits in dashboard.
403	Insufficient scope. API key lacks permissions.
404	Resource not found.
429	Rate limit exceeded. Check `X-RateLimit-Reset` header.
500	Server error. Retry or contact support.

Rate Limits

API Key: 10 req/min. Session: 20 req/min.
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix timestamp).

Workflow: Generate then poll

Generate: POST to the generation endpoint. Note the returned ID (videoId/imageId/musicId).
Poll: GET the status endpoint periodically (10-30s). Use exponential backoff.
Finish: When status === 'completed', use the result URL. When failed, surface error to user.
Edit (video only): POST to /videos/captions or /videos/overlay.

For full request/response shapes, see reference.md.