# Rawugc API Human Guide

## What This Is For
Procedural knowledge for agents to call the RawUGC API. It gives the agent a clearer input/output frame for rawugc API: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Rawugc API agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for rawugc API.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Rawugc API guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- **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.
- **Production**: `https://rawugc.com/api/v1`
- All paths below are relative to this base.
- **`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.
- **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).

## Decision Points And Nuance
The original skill emphasizes: Authentication, Base URL, API Versioning, Video Generation, POST /videos/generate, GET /videos/:videoId, GET /videos, POST /videos/captions, POST /videos/overlay, Image Generation.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- **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.
- If `RAWUGC_API_KEY` is missing or empty, inform the user they must set it and obtain a key from the RawUGC dashboard.
- | Field | Type | Required | Description |
- | `videoUrls` | string[] | For kling | URLs, max 1. Required for `kling-2.6/motion-control` |
- | `imageUrls` | string[] | For editing | Source images. Required for `google/nano-banana-edit`. Optional for `nano-banana-2` (reference images, max 14). |
- **POST /personas** -- Create. Body: `name` (required, max 200), `description` (required, max 5000). Returns `id`.
- **POST /messaging** -- Create. Body: `name` (required, max 200), `body` (required, max 5000). Returns `id`.
- **POST /products** -- Create. Body: `name` (required, max 200), `photos` (required, URL array), `description` (max 1000), `messaging` (max 5000). Returns `id`.

## Copy-And-Paste Prompt
```text
Use the Rawugc API human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the tfcbot/rawugc-skills skill entry for `rawugc-api`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

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