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):

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.

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

POST /videos/overlay

Add text overlay to a completed video.

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

---

Image Generation

POST /images/generate

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

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.

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.

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.

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.

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.

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.

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

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

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

---

Supporting file: reference.md

RawUGC API -- Request/Response Reference

Condensed shapes for agent lookups. Base URL: https://rawugc.com/api/v1. Auth: Authorization: Bearer <RAWUGC_API_KEY>. Version: RawUGC-Version: 2026-03-06.

---

Video Generation

POST /videos/generate

Request (application/json)

• model (required): sora-2-text-to-video | sora-2-image-to-video | kling-2.6/motion-control | veo3 | veo3_fast
• prompt (optional, required for text-to-video/veo3): string, 1-5000 chars
• imageUrls (optional, required for image-to-video/kling): string[], max 10. Veo3/veo3_fast accept up to 2.
• videoUrls (optional, required for kling): string[], max 1
• aspectRatio (optional): Sora: portrait | landscape. Veo3: 16:9 | 9:16 | Auto
• nFrames (optional, Sora only): "10" | "15"
• selectedCharacter (optional): string
• characterOrientation (optional, kling only): image | video
• mode (optional, kling only): 720p | 1080p

Response 201: videoId (vid_xxx), model, status, creditsUsed, newBalance, estimatedCompletionTime, createdAt (ms epoch)

GET /videos/{videoId}

Response 200: videoId, status (pending|processing|completed|failed), model, prompt?, creditsUsed, url? (completed), createdAt, completedAt?, failCode?, failMessage?, versions? (MediaVersion[])

MediaVersion: videoId, version (int), url, operation? (captions|overlay), createdAt

GET /videos

Query: status?, limit? (1-100, default 50), page? (default 1)

Response 200: videos (VideoResponse[]), pagination (total, page, pageSize, hasMore)

POST /videos/captions

Request: videoId (required), language? (e.g. en)

Response 200 (EditResponse): videoId, url, version, operation, creditsUsed (1)

POST /videos/overlay

Request: videoId (required), text (required, 1-500), position? (top|center|bottom), fontSize? (8-200), topBottomMargin? (0-500), strokeThickness? (0-10)

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

---

Image Generation

POST /images/generate

Request: model (required: nano-banana-2 | google/nano-banana-edit), prompt (required, 1-20000), imageUrls? (required for edit, optional for text-to-image, max 14), aspectRatio? (nano-banana-2), imageSize? (nano-banana-edit), resolution? (1K|2K|4K), outputFormat? (png|jpeg|jpg), googleSearch? (boolean, nano-banana-2 only)

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

GET /images/{imageId}

Response 200: imageId, status, model, prompt, url? (completed), imageSize?, resolution?, outputFormat?, creditsUsed, createdAt, completedAt?, failCode?, failMessage?

GET /images

Query: status?, limit? (1-100, default 20), page?

Response 200: images (ImageResponse[]), pagination (total, page, pageSize, hasMore)

---

Music Generation

POST /music/generate

Request: prompt (required, 1-2000), model? (V3_5|V4|V4_5|V4_5PLUS|V4_5ALL|V5, default V5), instrumental? (boolean, default true), title? (max 200), style? (max 500)

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

GET /music/{musicId}

Response 200: musicId, status, model, prompt, audioUrl? (completed), albumArtUrl?, duration?, title?, creditsUsed, createdAt, completedAt?, failCode?, failMessage?

GET /music

Query: status?, limit? (1-100, default 20), page?

Response 200: tracks (MusicResponse[]), pagination (total, page, pageSize, hasMore)

---

Upload

POST /upload

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

Response 200: url (public URL for use in generation requests), contentType, size (bytes)

---

Characters

GET /characters

Response 200: characters (CharacterResponse[]), count, adminCount, userCount

GET /characters/{characterId}

CharacterResponse: _id, username, displayName, description, videoPreviewUrl?, type (admin|user), isActive, createdAt, updatedAt

---

Personas

GET /personas

Response 200: personas (PersonaResponse[]), count

POST /personas

Request: name (required, max 200), description (required, max 5000)

Response 201: { id }

GET /personas/{personaId}

Response 200: PersonaResponse

PATCH /personas/{personaId}

Request: name?, description?

DELETE /personas/{personaId}

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

---

Messaging

GET /messaging

Response 200: messages (MessagingResponse[]), count

POST /messaging

Request: name (required, max 200), body (required, max 5000)

Response 201: { id }

GET /messaging/{messageId}

PATCH /messaging/{messageId}

Request: name?, body?

DELETE /messaging/{messageId}

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

---

Products

GET /products

Response 200: products (ProductResponse[]), count

POST /products

Request: name (required, max 200), photos (required, URL[]), description? (max 1000), messaging? (max 5000)

Response 201: { id }

GET /products/{productId}

PATCH /products/{productId}

Request: name?, description?, photos?, messaging?

DELETE /products/{productId}

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

---

Styles

GET /styles

Query: type? (video|image)

Response 200: styles (StyleResponse[]), count

POST /styles

Request: name (required, max 200), description? (max 1000), type? (video|image), aspectRatio? (portrait|landscape|square), promptTemplate? (max 5000, placeholders: {productName}, {messaging}, {character})

Response 201: { id }

GET /styles/{styleId}

PATCH /styles/{styleId}

Request: name?, description?, aspectRatio?, promptTemplate?

DELETE /styles/{styleId}

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

---

Social Accounts

GET /social/accounts

Response 200: accounts (SocialAccount[]), count

POST /social/accounts

Sync accounts from scheduling provider. Response 200: { success }

DELETE /social/accounts/{accountId}

Response 200: { success }

SocialAccount: accountId, platform (tiktok|instagram|youtube), username, displayName, profilePicture?, isActive

---

Social Posts

POST /social/posts

Request: videoUrl (required), accountIds (required, string[]), mode (required: schedule|draft|now), scheduledFor? (ms, required for schedule), timezone? (IANA, default UTC), content? (max 2200), videoId?, publishToInbox?, tiktokPrivacyLevel? (SELF_ONLY|PUBLIC_TO_EVERYONE|MUTUAL_FOLLOW_FRIENDS|FOLLOWER_OF_CREATOR), tiktokAllowComment?, tiktokAllowDuet?, tiktokAllowStitch?, tiktokCommercialContentType? (none|brand_organic|brand_content)

Response 201: SocialPost

GET /social/posts

Query: fromDate? (ms), toDate? (ms), includeDrafts? (boolean)

Response 200: posts (SocialPost[]), count

GET /social/posts/{postId}

PATCH /social/posts/{postId}

Request: content?, scheduledFor?, timezone?, accountIds? (at least one field)

DELETE /social/posts/{postId}

Response 200: { success }

POST /social/posts/{postId}/reschedule

Request: scheduledFor (required, ms), timezone?

POST /social/posts/{postId}/publish

Immediately publish a draft.

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

---

Viral Library

GET /viral-library/videos/{videoId}

Response 200: ViralLibraryVideo

ViralLibraryVideo: id, tiktokId, tiktokUrl, username, description, stats (views, likes, comments, shares, saves), hashtags, soundName, duration, thumbnailUrl, playUrl, analysis? (VideoAnalysis)

VideoAnalysis: hook, summary, whyItPerformed, attributesToCopy, hooksToTest, keyframes (array: timestamp, type, description, visual, audio, text), durationSeconds, tags, analyzedAt

GET /viral-library/search

Query: q (required, natural language), limit? (1-50, default 20)

Response 200: results (array of { video: ViralLibraryVideo, score: number }), query, total

---

Research

POST /scrape-tiktok

Request: query (required, max 500), mode? (keyword|hashtag|search, default keyword), limit? (1-10, default 10)

Response 200: scrapeId, count, videos (array: id, url, author, description, stats {views, likes, comments, shares}, duration, hashtags, thumbnail?, videoUrl?)

POST /content-plans

Request: scrapeId (required), brief (required, max 5000)

Response 200: planId, scrapeId, brief, topWins, gapsToTest, blueprints (array: category, strategy, evidence, contentIdeas [{hook, openingShot, contentOutline, cta}])

GET /content-plans

Response 200: plans (array: planId, scrapeId, brief, createdAt), count

POST /analyze-video

Request: videoUrl (required), prompt? (max 5000)

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

---

Error body (ApiError)

All error responses use RFC 7807: type, title, status, detail?, instance?, errors? (Record<string, string[]>)

Status codes: 400 validation, 401 auth, 402 insufficient credits, 403 insufficient scope, 404 not found, 429 rate limit, 500 server error.

Rate limit headers

All responses include: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix timestamp seconds).