johnalbertini14-glitch RawUGC Video Generation API
Procedural knowledge for agents to call the RawUGC Video Generation 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_KEYis 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.
Endpoints
POST /videos/generate
Initiate video generation.
Request body (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
model |
string | Yes | One of: 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). Required for sora-2-text-to-video, veo3, veo3_fast |
imageUrls |
string[] | For image-to-video / kling | Array of image URLs (max 10). Required for sora-2-image-to-video; for kling-2.6/motion-control also requires videoUrls |
videoUrls |
string[] | For kling | Array of video URLs (max 1). Required only for kling-2.6/motion-control |
aspectRatio |
string | No | portrait or landscape (some models also support 16:9, 9:16, Auto) |
nFrames |
string | No | "10" or "15" (video length) |
selectedCharacter |
string | No | Character username (e.g. rawugc.mia) |
characterOrientation |
string | No | image or video |
mode |
string | No | 720p or 1080p (for supported models) |
Response (201): taskId, model, status (e.g. pending), creditsUsed, newBalance, estimatedCompletionTime, createdAt.
GET /videos/:taskId
Get status of a generation task. Path parameter: taskId (from the generate response).
Response (200): taskId, status (pending | processing | completed | failed), model, prompt, creditsUsed, resultUrl (when status === 'completed'), createdAt, completedAt, failCode, failMessage, progress (0–100).
GET /videos
List the user's videos with optional filters and pagination.
Query parameters: status (optional: pending | processing | completed | failed), limit (1–100, default 50), page (default 1).
Response (200): videos (array of same shape as GET /videos/:taskId), pagination: total, page, pageSize, hasMore.
Errors
Responses use RFC 7807 Problem Details (JSON): type, title, status (HTTP code), detail, optional instance, optional errors (field-specific validation messages).
| Status | Meaning |
|---|---|
| 400 | Validation error (invalid body or params). Surface detail and errors to the user. |
| 401 | Authentication error (missing or invalid API key). Tell user to check RAWUGC_API_KEY. |
| 402 | Insufficient credits. User must add credits in RawUGC dashboard. |
| 404 | Video not found (GET /videos/:taskId). |
| 429 | Rate limit exceeded. Retry after the time indicated by response or back off. |
| 500 | Internal server error. Suggest retry or contact support. |
Workflow: Generate then poll
- Generate:
POST /videos/generatewith the desired body. On 201, notetaskId. - Poll: Call
GET /videos/:taskIdperiodically (e.g. every 10–30 seconds). Optionally use exponential backoff. - Finish: When
status === 'completed', useresultUrlfor the video. Whenstatus === 'failed', surfacefailCodeandfailMessageto the user.
For full request/response shapes and status codes, see reference.md.