# Revid Public API v3 — Endpoint Reference

> All endpoints of the Revid public API. Base URL: `https://www.revid.ai`. Auth: header `key: YOUR_API_KEY` unless noted (key from https://www.revid.ai/account).

| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
| `/api/public/v3/render` | POST | Yes | Create a video |
| `/api/public/v3/render` | GET | No | Get live JSON docs |
| `/api/public/v3/calculate-credits` | POST | No | Estimate credits |
| `/api/public/v3/status` | GET | Yes | Get render status |
| `/api/public/v3/projects` | GET | Yes | List projects |
| `/api/public/v3/me` | GET | Yes | Get account info |
| `/api/public/v3/export-video` | POST | Yes | Export project to mp4 |
| `/api/public/v3/rename-project` | POST | Yes | Rename project |
| `/api/public/v3/add-to-queue` | POST | Yes | Schedule publishing |
| `/api/public/v3/publish-now` | POST | Yes | Publish immediately |
| `/api/public/v3/consistent-characters` | GET | Yes | List characters |
| `/api/public/v3/consistent-characters` | POST | Yes | Create character |
| `/api/public/v3/consistent-characters` | DELETE | Yes | Delete character |
| `/api/public/v3/voice-clone` | POST | Yes | Clone a voice |
| `/api/public/v3/generate-media` | POST | Yes | Generate standalone media |
| `/api/public/v3/buy-credit-pack` | POST | Yes | Buy credit pack (auto top-up) |

## POST /api/public/v3/render — Create a video

Start a video generation. Returns a project id (pid) immediately; the render continues asynchronously. Use webhookUrl or poll GET /status.

**Cost:** 10 credits per call + generation costs (estimate with /calculate-credits).

Body: the workflow-driven render request. See the per-workflow guides:

- [Script to video](https://www.revid.ai/llm/api/script-to-video.md) — requires source.text
- [Prompt to video](https://www.revid.ai/llm/api/prompt-to-video.md) — requires source.prompt
- [Audio to video](https://www.revid.ai/llm/api/audio-to-video.md) — requires source.url
- [Music to video](https://www.revid.ai/llm/api/music-to-video.md) — requires source.url
- [Article to video](https://www.revid.ai/llm/api/article-to-video.md) — requires source.url
- [Avatar to video](https://www.revid.ai/llm/api/avatar-to-video.md) — requires source.text + avatar.url
- [Static background video](https://www.revid.ai/llm/api/static-background-video.md) — requires source.text or source.url
- [Motion transfer](https://www.revid.ai/llm/api/motion-transfer.md) — requires source.url + media.provided[] with 1 image (the target character)
- [Caption video](https://www.revid.ai/llm/api/caption-video.md) — requires source.url
- [Ad generator](https://www.revid.ai/llm/api/ad-generator.md) — requires source.prompt or media.provided[]

Response: { success: 1, pid, workflow, webhookUrl, endpoint, docs }. The webhook receives the final status and video URL.

## GET /api/public/v3/render — Get live JSON docs

Returns this API's machine-readable documentation: workflows, defaults, parameter reference, and examples. No auth required.

Response: JSON documentation payload (workflows, parameterReference, examples, additionalEndpoints, compatibility).

## POST /api/public/v3/calculate-credits — Estimate credits

Estimate the credit cost of a render without starting it. Accepts the exact same body as POST /render (legacy { creationParams } also accepted). No auth required.

Body: the workflow-driven render request. See the per-workflow guides:

- [Script to video](https://www.revid.ai/llm/api/script-to-video.md) — requires source.text
- [Prompt to video](https://www.revid.ai/llm/api/prompt-to-video.md) — requires source.prompt
- [Audio to video](https://www.revid.ai/llm/api/audio-to-video.md) — requires source.url
- [Music to video](https://www.revid.ai/llm/api/music-to-video.md) — requires source.url
- [Article to video](https://www.revid.ai/llm/api/article-to-video.md) — requires source.url
- [Avatar to video](https://www.revid.ai/llm/api/avatar-to-video.md) — requires source.text + avatar.url
- [Static background video](https://www.revid.ai/llm/api/static-background-video.md) — requires source.text or source.url
- [Motion transfer](https://www.revid.ai/llm/api/motion-transfer.md) — requires source.url + media.provided[] with 1 image (the target character)
- [Caption video](https://www.revid.ai/llm/api/caption-video.md) — requires source.url
- [Ad generator](https://www.revid.ai/llm/api/ad-generator.md) — requires source.prompt or media.provided[]

Response: Estimated credit breakdown for the given payload.

## GET /api/public/v3/status — Get render status

Poll the status of a project created by POST /render.

Query parameters:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `pid` | string | Yes |  | Project id returned by POST /render. |

Response: Project status (building/rendering/ready/error), progress, and the output video URL when ready.

## GET /api/public/v3/projects — List projects

List projects owned by the API key's workspace.

Query parameters:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `limit` | integer | No |  | Maximum number of projects to return. |

Response: Array of projects with ids, names, statuses, and output URLs.

## GET /api/public/v3/me — Get account info

Account, credits, subscription, and workspace info for the API key.

Response: { success, email, totalCredits, user, workspace, credits: { regular, nonExpiring, total }, subscription, usage }.

## POST /api/public/v3/export-video — Export project to mp4

Render an mp4 export of an existing project.

**Cost:** 10 credits.

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `pid` | string | Yes |  | Project id to export. Must belong to the API key user. |

Response: Export result with the video file URL.

## POST /api/public/v3/rename-project — Rename project

Rename a project owned by the API key user.

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `pid` | string | Yes |  | Project id. |
| `name` | string | Yes |  | New project name. |

Response: { success: 1 } on success.

## POST /api/public/v3/add-to-queue — Schedule publishing

Add a rendered video to your publishing queue; it is scheduled at the next available slot of the channel.

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `videoUrl` | string | Yes |  | Public URL of the rendered video to publish. |
| `channelName` | string | either channelName/channelId or at least one platform account |  | Name of a channel configured in your Revid account settings. Mutually exclusive with platform accounts. |
| `channelId` | string | No |  | Channel id, alternative to channelName. |
| `tiktok` | object | No |  | TikTok target: { username or id, title?, privacy_level? }. privacy_level: PUBLIC_TO_EVERYONE, FOLLOWER_OF_CREATOR, MUTUAL_FOLLOW_FRIENDS, SELF_ONLY. |
| `youtube` | object | No |  | YouTube target: { username or id, title?, description? }. |
| `instagram` | object | No |  | Instagram target: { username or id, caption? }. |
| `webhook` | object | No |  | Webhook target: { username or id }. Posts the video to your configured webhook. |
| `extraParams` | object | No |  | Extra fields stored on the scheduled content (title, description, ...). |

Response: Scheduled content entry with the computed publish time.

## POST /api/public/v3/publish-now — Publish immediately

Publish a rendered video right now to a channel or specific platform accounts.

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `videoUrl` | string | Yes |  | Public URL of the rendered video to publish. |
| `channelName` | string | either channelName/channelId or at least one platform account |  | Name of a channel configured in your Revid account settings. Mutually exclusive with platform accounts. |
| `channelId` | string | No |  | Channel id, alternative to channelName. |
| `tiktok` | object | No |  | TikTok target: { username or id, title?, privacy_level? }. privacy_level: PUBLIC_TO_EVERYONE, FOLLOWER_OF_CREATOR, MUTUAL_FOLLOW_FRIENDS, SELF_ONLY. |
| `youtube` | object | No |  | YouTube target: { username or id, title?, description? }. |
| `instagram` | object | No |  | Instagram target: { username or id, caption? }. |
| `webhook` | object | No |  | Webhook target: { username or id }. Posts the video to your configured webhook. |
| `extraParams` | object | No |  | Extra fields stored on the scheduled content (title, description, ...). |

Response: Publish result per platform.

## GET /api/public/v3/consistent-characters — List characters

List saved consistent characters (avatar-based and LoRA-trained), newest first.

Response: Array of { id, name, description, imageUrl, contentType, source: avatar|lora, createdAt }.

## POST /api/public/v3/consistent-characters — Create character

Save a consistent character usable in renders (characterIds) and as a talking avatar.

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `name` | string | Yes |  | Character name (min 3 characters). |
| `description` | string | Yes |  | Character description (min 10 characters) — used by the AI to decide when/how to use the character. |
| `imageUrl` | string | Yes |  | Public URL of the character image. |

Response: Created character with its id.

## DELETE /api/public/v3/consistent-characters — Delete character

Delete a character by id (works for avatar-based and LoRA characters).

Query parameters:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `id` | string | Yes |  | Character id (also accepted in the body). |

Response: { success, deleted: id, source: avatar|lora }.

## POST /api/public/v3/voice-clone — Clone a voice

Clone a custom voice from a public audio sample. Requires the Elite plan or above (10 voices on Elite, 100 on Enterprise).

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `name` | string | Yes |  | Voice name (min 3 characters). |
| `description` | string | No |  | Voice description. |
| `voiceUrl` | string | Yes |  | Public URL of the audio sample (mp3, wav, ...). |

Response: { success, voiceId, voice } — use voiceId as voice.voiceId in renders.

## POST /api/public/v3/generate-media — Generate standalone media

Generate images or video clips without creating a video project (same engine as the Revid media generator).

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `mediaType` | string | No | `image`, `video` | What to generate. |
| `prompt` | string | yes, unless mediaType = video with firstFrame |  | Generation prompt. Aliases: source.prompt, input. |
| `ratio` | string | No |  | Aspect ratio: 1:1, 9:16, 16:9 (aliases square/portrait/landscape). Alias: aspectRatio. |
| `imageQuality` | string | No | `cheap`, `good`, `ultra` | Image model: cheap, good, ultra. Alias: media.imageModel. |
| `videoQuality` | string | No | `base`, `pro`, `ultra`, `veo3`, `sora2` | Video model: base, pro, ultra, veo3, sora2. Alias: media.videoModel. |
| `count` | integer | No |  | Number of images (videos: always 1). Aliases: imageCount, options.outputCount. |
| `duration` | integer | No |  | Video duration in seconds (video only). |
| `generationPreset` | string | No |  | Visual style preset slug (same list as media.mediaPreset). |
| `firstFrame` | string | No |  | URL of the first frame to animate from (video only). |
| `lastFrame` | string | No |  | URL of the last frame to animate to (video only). |
| `referenceImages` | string[] | No |  | Reference image URLs (max 4 for images, 9 for videos). |
| `referenceVideos` | string[] | No |  | Reference video URLs (max 3). |
| `referenceAudios` | string[] | No |  | Reference audio URLs (max 3). |
| `enableAudio` | boolean | No |  | Generate ambient audio with the video clip. |
| `selectedCharacters` | string[] | No |  | Consistent character ids to feature (max 12). Alias: characterIds. |
| `improvePrompt` | boolean | No |  | Let the AI rewrite/improve the prompt before generation. |
| `withTranscript` | boolean | No |  | Return a transcript with the generated media. |
| `voiceId` | string | No |  | Voice id when generating media with speech. |

Response: { success, mediaType, generationOptions, ...generation result with media URLs }.

## POST /api/public/v3/buy-credit-pack — Buy credit pack (auto top-up)

Charge the saved payment method for a credit pack. Used for automated top-up flows.

Body fields:

| Field | Type | Required | Allowed | Description |
|---|---|---|---|---|
| `source` | string | Yes | `auto_topup` | Must be "auto_topup". |

Response: Invoice metadata for the purchase.

## Reference data

- Visual style presets (media.mediaPreset): `DEFAULT`, `GHIBLI`, `PIXAR`, `ANIME`, `ANIME_SR`, `REALISM`, `ULTRA_REALISM`, `FLAT_ANIMATION`, `SKETCH_COLOR`, `SKETCH_BW`, `INK`, `RENDER_3D`, `LOW_POLY`, `LEGO`, `SCIFI`, `RECRO_CARTOON`, `PIXEL_ART`, `FANTASY`, `MOVIE`, `STYLIZED_ILLUSTRATION`, `MANGA_COLOR`, `MANGA_BW`, `CREATIVE`, `PHOTOGRAPHY`, `RAYTRACED`, `ENVIRONMENT`, `ILLUSTRATION`, `SPIDER`, `CHILDRENS_BOOK_ILLUSTRATIONS`, `NINTENDO`, `MINECRAFT`, `NEW_YORKER`, `1950S_ADVERTISEMENT`, `RENAISSANCE_FRESCO`, `MODERN_NOIR_MINIMALISM`, `EXPRESSIVE_INK_MINIMALISM`, `GILDED_COSMIC_BAROQUE`, `EPIC_LINEBURST`, `HAUNTED_LINEWORK`, `CLAYMATION`, `R_TECHNICAL_NANOBANANAPRO`, `R_TECHNICAL_DRAWING_RECRAFT`
- Caption presets (captions.preset): `Basic`, `Revid`, `Hormozi`, `Ali`, `Wrap 1`, `Wrap 2`, `Faceless`, `Elegant`, `Difference`, `Opacity`, `Playful`, `Bold Punch`, `Movie`, `Outline`, `Cove`, `Beat`, `Floating`, `Gram`, `Word by Word`
- Music tracks (music.trackName): 115+ tracks, e.g. `Observer`, `Snaps`, `Bright Morning`, `Chill Wave`, `Acoustic Calm`, `Adventure Time`, `Celebration`, `Don't Blink`, `Sky's the Limit`, `Powerful Motivation`, `Battle Orchestra`, `Dark Sci-Fi`, `Calm One`, `Roaming Free`, `Cartoon`

## Error model

- 400 — validation error. The message names the exact field, e.g. "voice.speed must be between 0.5 and 2."
- 401 — missing or invalid API key (header `key`).
- 500 — internal error. Credits consumed by a failed render are refunded automatically.

Machine-readable spec: https://www.revid.ai/postman/revid-public-v3-render.openapi.json · Postman: https://www.revid.ai/postman/revid-public-v3-render.master.postman_collection.json · Interactive docs: https://www.revid.ai/docs