rawugc-api

Call the RawUGC API to generate AI videos/images/music, manage content (personas, products, styles, characters), schedule social media posts, research TikTok content, and analyze viral videos. Use when the user wants to interact with any RawUGC API endpoint.

# 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`