{ "openapi": "3.1.0", "info": { "title": "Faceless.so API", "version": "1.1.12", "description": "Public API for Faceless.so: generate AI faceless videos from scripts, run automated video series and publish to YouTube, TikTok, Instagram, X, Facebook, LinkedIn and Threads. Authenticate with an API key from https://faceless.so/developers. Success responses are { success: true, data, pagination? }; errors are { success: false, error: { type, message } }. Mutating operations accept an Idempotency-Key header.", "contact": { "url": "https://faceless.so/developers" } }, "servers": [ { "url": "https://faceless.so/api/v1" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "me" }, { "name": "credits" }, { "name": "videos" }, { "name": "renders" }, { "name": "series" }, { "name": "posts" }, { "name": "accounts" }, { "name": "catalog" }, { "name": "assets" }, { "name": "analytics" } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Identify the caller", "description": "Returns the team this API key belongs to, its credit balance, subscription plan and the scopes granted to the key. Call this first to verify authentication and discover the team context every other operation runs in.", "tags": [ "me" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "team": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "credits": { "type": "integer" } } }, "plan": { "type": "string" }, "auth": { "type": "object", "properties": { "via": { "type": "string" }, "keyPrefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "legacy": { "type": "boolean" } } } } } } }, "example": { "success": true, "data": { "team": { "id": "665f1b2a9c31a2b3c4d5e601", "name": "My Channel", "credits": 340 }, "plan": "creator", "auth": { "via": "api_key", "keyPrefix": "fl_live_a1b2c3d4", "scopes": [ "videos:read", "videos:write" ], "legacy": false } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [], "x-credit-cost": "none", "x-cli-command": "faceless whoami", "x-mcp-tool": "faceless_get_me" } }, "/credits": { "get": { "operationId": "getCredits", "summary": "Credit balance and history", "description": "Returns the team's current credit balance and a paginated ledger of credit transactions (purchases, subscription grants, video spends, refunds). Video creation charges credits at creation time; rendering and publishing are free. Costs: storyboard 20, motion_lite 50, motion_pro 100 credits per video.", "tags": [ "credits" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, starting at 1" }, "description": "Page number, starting at 1" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page (max 100)" }, "description": "Items per page (max 100)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "balance": { "type": "integer" }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "credits": { "type": "integer" }, "type": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string" } } } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "success": true, "data": { "balance": 340, "history": [ { "id": "665f1b2a9c31a2b3c4d5e701", "credits": -50, "type": "spending", "description": "Faceless video (motion_lite)", "createdAt": "2026-07-30T10:00:00.000Z" } ] }, "pagination": { "page": 1, "limit": 20, "total": 1 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "credits:read" ], "x-credit-cost": "none", "x-cli-command": "faceless credits", "x-mcp-tool": "faceless_get_credits" } }, "/videos": { "post": { "operationId": "createVideo", "summary": "Create a faceless video from a script", "description": "Creates an AI faceless video from a finished narration script: TTS voiceover, AI-generated visuals per scene, captions and optional background music. Generation is asynchronous; the response returns the video id immediately. Poll GET /videos/{id}/status until status is completed, then call POST /videos/{id}/render to produce the final MP4. Credits are charged now, at creation.", "tags": [ "videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "script": { "type": "string", "minLength": 10, "maxLength": 10000, "description": "The full narration script the video is generated from" }, "voiceId": { "type": "string", "description": "TTS voice id for the narration. Full list: GET /voices" }, "model": { "type": "string", "enum": [ "storyboard", "motion_lite", "motion_pro" ], "default": "storyboard", "description": "Generation model: storyboard (20 credits, static scenes), motion_lite (50, animated transitions), motion_pro (100, cinematic)" }, "style": { "type": "string", "description": "Visual style for generated imagery. Full list: GET /options?kind=styles" }, "language": { "type": "string", "description": "Script language, e.g. English. Full list: GET /options?kind=languages" }, "name": { "type": "string", "maxLength": 120, "description": "Project name; defaults to the start of the script" }, "enableBackgroundMusic": { "type": "boolean", "description": "Mix background music under the narration" }, "masterStyle": { "type": "string", "description": "Extra style directive applied to every generated scene" }, "globalNegativePrompt": { "type": "string", "description": "Things the image model should avoid in every scene" } }, "required": [ "script", "voiceId" ], "additionalProperties": false }, "example": { "script": "Did you know the ocean has lakes and rivers of its own? ...", "voiceId": "EXAVITQu4vr4xnSDxMaL", "model": "storyboard" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "model": { "type": "string" }, "status": { "type": "string" }, "creditsUsed": { "type": "integer" }, "statusUrl": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e801", "name": "Did you kn...", "model": "storyboard", "status": "processing", "creditsUsed": 20, "statusUrl": "/api/v1/videos/665f1b2a9c31a2b3c4d5e801/status" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:write" ], "x-credit-cost": "20 credits (storyboard), 50 (motion_lite) or 100 (motion_pro) per video, charged at creation", "x-idempotent": true, "x-rate-limit": { "max": 10, "windowSec": 60 }, "x-cli-command": "faceless videos create", "x-mcp-tool": "faceless_create_video" }, "get": { "operationId": "listVideos", "summary": "List the team's videos", "description": "Returns a paginated list of the team's video projects, newest first, with generation status and the rendered MP4 URL when available.", "tags": [ "videos" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, starting at 1" }, "description": "Page number, starting at 1" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page (max 100)" }, "description": "Items per page (max 100)" }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only archived videos when true" }, "description": "Only archived videos when true" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "model": { "type": "string" }, "renderedVideoUrl": { "type": "string" }, "createdAt": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "success": true, "data": [ { "id": "665f1b2a9c31a2b3c4d5e801", "name": "Ocean facts", "platform": "tts", "model": "storyboard", "renderedVideoUrl": "https://exports.faceless.so/renders/665f1b2a9c31a2b3c4d5e801/1730000000000.mp4", "createdAt": "2026-07-30T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:read" ], "x-credit-cost": "none", "x-cli-command": "faceless videos list", "x-mcp-tool": "faceless_list_videos" } }, "/videos/captions": { "post": { "operationId": "createCaptionVideo", "summary": "Caption an existing video or audio file", "description": "Creates a project from a video or audio URL you already have: transcribes it, adds styled captions and emojis, and makes it editable. Use this to caption existing footage rather than generate new AI visuals (for that, use POST /videos). Processing is asynchronous; poll GET /videos/{id}/status.", "tags": [ "videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "videoUrl": { "type": "string", "format": "uri", "description": "Public URL of the video file to caption" }, "audioUrl": { "type": "string", "format": "uri", "description": "Public URL of an audio file to turn into a captioned video" }, "name": { "type": "string", "maxLength": 120, "description": "Project name" }, "language": { "type": "string", "description": "Spoken language of the file, e.g. English" } }, "additionalProperties": false }, "example": { "videoUrl": "https://example.com/clip.mp4", "language": "English" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "statusUrl": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e802", "status": "processing", "statusUrl": "/api/v1/videos/665f1b2a9c31a2b3c4d5e802/status" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:write" ], "x-credit-cost": "none", "x-idempotent": true, "x-rate-limit": { "max": 10, "windowSec": 300 }, "x-cli-command": "faceless videos captions", "x-mcp-tool": "faceless_create_caption_video" } }, "/videos/{id}": { "get": { "operationId": "getVideo", "summary": "Get one video", "description": "Returns a single video project: script, voice, model, generation state, per-platform post metadata and the rendered MP4 URL once rendered.", "tags": [ "videos" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "platform": { "type": "string" }, "model": { "type": "string" }, "script": { "type": "string" }, "voiceId": { "type": "string" }, "status": { "type": "string" }, "renderedVideoUrl": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "thumbnails": { "type": "object", "properties": { "status": { "type": "string" }, "generation": { "type": "integer" }, "aspect": { "type": "string" }, "selectedVariantId": { "type": "string" }, "selectedBy": { "type": "string" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "hookText": { "type": "string" }, "source": { "type": "string" }, "score": { "type": "integer" }, "grade": { "type": "string" } } } } } }, "createdAt": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e801", "name": "Ocean facts", "platform": "tts", "model": "storyboard", "script": "Did you know...", "voiceId": "EXAVITQu4vr4xnSDxMaL", "status": "completed", "renderedVideoUrl": "https://exports.faceless.so/renders/665f1b2a9c31a2b3c4d5e801/1722333444555.mp4", "thumbnailUrl": "https://exports.faceless.so/thumbnails/665f1b2a9c31a2b3c4d5e801/1/a1b2c3d4.jpg", "thumbnails": { "status": "ready", "generation": 1, "aspect": "9:16", "selectedVariantId": "a1b2c3d4-0000-4000-8000-000000000001", "selectedBy": "ai", "variants": [ { "id": "a1b2c3d4-0000-4000-8000-000000000001", "url": "https://exports.faceless.so/thumbnails/665f1b2a9c31a2b3c4d5e801/1/a1b2c3d4.jpg", "hookText": "OCEAN RIVERS", "source": "ai", "score": 88, "grade": "S" } ] }, "createdAt": "2026-07-30T10:00:00.000Z" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:read" ], "x-credit-cost": "none", "x-cli-command": "faceless videos get", "x-mcp-tool": "faceless_get_video" }, "patch": { "operationId": "updateVideo", "summary": "Update a video's name or post metadata", "description": "Updates a video's name and/or its per-platform post metadata (titles, captions, descriptions). Set the metadata for every platform you intend to schedule to BEFORE calling POST /posts/schedule; scheduling rejects platforms whose metadata is missing.", "tags": [ "videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "description": "Project name" }, "youtubePost": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 100, "description": "YouTube title (max 100 chars)" }, "description": { "type": "string", "maxLength": 5000, "description": "YouTube description" }, "privacyStatus": { "type": "string", "enum": [ "public", "unlisted", "private" ], "description": "Defaults to public" } }, "required": [ "title" ], "additionalProperties": false, "description": "YouTube post metadata; required before scheduling to YouTube" }, "tiktokPost": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 2200, "description": "TikTok caption" } }, "required": [ "title" ], "additionalProperties": false, "description": "TikTok post metadata; required before scheduling to TikTok" }, "instagramPost": { "type": "object", "properties": { "caption": { "type": "string", "maxLength": 2200, "description": "Instagram caption" } }, "required": [ "caption" ], "additionalProperties": false, "description": "Instagram post metadata; required before scheduling to Instagram" }, "xPost": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 280, "description": "X post text (max 280 chars)" } }, "required": [ "text" ], "additionalProperties": false, "description": "X post metadata; required before scheduling to X" }, "facebookPost": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 5000, "description": "Facebook description" } }, "required": [ "description" ], "additionalProperties": false, "description": "Facebook post metadata; required before scheduling to Facebook" }, "linkedinPost": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 3000, "description": "LinkedIn description" } }, "required": [ "description" ], "additionalProperties": false, "description": "LinkedIn post metadata; required before scheduling to LinkedIn" }, "threadsPost": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500, "description": "Threads post text" } }, "required": [ "text" ], "additionalProperties": false, "description": "Threads post metadata; required before scheduling to Threads" } }, "additionalProperties": false }, "example": { "youtubePost": { "title": "The ocean has rivers underwater", "privacyStatus": "public" }, "tiktokPost": { "title": "underwater rivers are real #ocean" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "youtubePost": { "type": "object", "properties": { "title": { "type": "string" } } }, "thumbnailUrl": { "type": "string" }, "thumbnails": { "type": "object", "properties": { "status": { "type": "string" }, "selectedBy": { "type": "string" }, "variants": { "type": "array", "items": { "type": "string" } } } } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e801", "name": "Ocean facts", "youtubePost": { "title": "The ocean has rivers underwater" }, "thumbnailUrl": "https://exports.faceless.so/thumbnails/665f1b2a9c31a2b3c4d5e801/1/a1b2c3d4.jpg", "thumbnails": { "status": "ready", "selectedBy": "ai", "variants": [ "https://exports.faceless.so/thumbnails/665f1b2a9c31a2b3c4d5e801/a.jpg" ] } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:write" ], "x-credit-cost": "none", "x-cli-command": "faceless videos update", "x-mcp-tool": "faceless_update_video" }, "delete": { "operationId": "deleteVideo", "summary": "Delete a video", "description": "Permanently deletes a video project and its generated assets. This cannot be undone and does not refund credits.", "tags": [ "videos" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "example": { "success": true, "data": { "deleted": true } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:write" ], "x-credit-cost": "none", "x-cli-command": "faceless videos delete", "x-mcp-tool": "faceless_delete_video" } }, "/videos/{id}/thumbnail": { "post": { "operationId": "selectVideoThumbnail", "summary": "Choose which thumbnail a video uses", "description": "Selects one of the video's thumbnail variants as the effective thumbnail. Read the available variants from GET /videos/{id} (the thumbnails object). The choice is marked as a user pick, so later automatic regenerations will not overwrite it, and it is what gets pushed to YouTube and used as the Instagram Reels cover at post time. Thumbnails are free and generated automatically after a video completes.", "tags": [ "videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1, "description": "Variant id from the thumbnails.variants array on GET /videos/{id}" } }, "required": [ "variantId" ], "additionalProperties": false }, "example": { "variantId": "a1b2c3d4-0000-4000-8000-000000000002" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "thumbnails": { "type": "object", "properties": { "status": { "type": "string" }, "selectedVariantId": { "type": "string" }, "selectedBy": { "type": "string" }, "variants": { "type": "array", "items": { "type": "string" } } } } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e801", "thumbnailUrl": "https://exports.faceless.so/thumbnails/665f1b2a9c31a2b3c4d5e801/1/b2c3d4e5.jpg", "thumbnails": { "status": "ready", "selectedVariantId": "a1b2c3d4-0000-4000-8000-000000000002", "selectedBy": "user", "variants": [ "https://exports.faceless.so/thumbnails/665f1b2a9c31a2b3c4d5e801/a.jpg" ] } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:write" ], "x-credit-cost": "none", "x-cli-command": "faceless videos select-thumbnail", "x-mcp-tool": "faceless_select_video_thumbnail" } }, "/videos/{id}/status": { "get": { "operationId": "getVideoStatus", "summary": "Poll video generation progress", "description": "Returns generation progress for a video: overall status (pending, processing, completed, failed), percent complete, per-step events and any error messages. Poll every 10-30 seconds after POST /videos until status is completed, then render it with POST /videos/{id}/render. A failed generation refunds nothing automatically; check errorMessages.", "tags": [ "videos" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "percentCompleted": { "type": "integer" }, "readyForEditing": { "type": "boolean" }, "errorMessages": { "type": "array", "items": { "type": "string" } }, "renderedVideoUrl": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e801", "status": "processing", "percentCompleted": 62, "readyForEditing": false, "errorMessages": [ "b-roll fetch timed out, retried" ], "renderedVideoUrl": "https://exports.faceless.so/renders/665f1b2a9c31a2b3c4d5e801/1730000000000.mp4" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:read" ], "x-credit-cost": "none", "x-terminal-states": [ "completed", "failed" ], "x-cli-command": "faceless videos status", "x-mcp-tool": "faceless_get_video_status" } }, "/videos/{id}/render": { "post": { "operationId": "renderVideo", "summary": "Render a video to MP4", "description": "Starts a cloud render of a generated video and returns a renderId. Rendering is asynchronous: poll GET /renders/{renderId} until status is done to get the MP4 URL. The video must have finished generating first (getVideoStatus status completed). Rendering is free; credits were charged at creation.", "tags": [ "videos" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "h264", "vp8" ], "default": "h264", "description": "Output codec; h264 for MP4 (default)" } }, "additionalProperties": false }, "example": { "codec": "h264" } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "renderId": { "type": "string" }, "statusUrl": { "type": "string" } } } } }, "example": { "success": true, "data": { "renderId": "abcd1234efgh", "statusUrl": "/api/v1/renders/abcd1234efgh" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:write" ], "x-credit-cost": "none", "x-idempotent": true, "x-rate-limit": { "max": 10, "windowSec": 300 }, "x-cli-command": "faceless videos render", "x-mcp-tool": "faceless_render_video" } }, "/renders/{id}": { "get": { "operationId": "getRender", "summary": "Poll render progress", "description": "Returns the progress of a render started by POST /videos/{id}/render: status in-progress (with overallProgress 0-1), done (with the final MP4 url) or error. Poll every 5-15 seconds; renders typically take under two minutes.", "tags": [ "renders" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "renderId": { "type": "string" }, "status": { "type": "string" }, "overallProgress": { "type": "integer" }, "url": { "type": "string" } } } } }, "example": { "success": true, "data": { "renderId": "abcd1234efgh", "status": "done", "overallProgress": 1, "url": "https://exports.faceless.so/renders/665f1b2a9c31a2b3c4d5e801/1722333444555.mp4" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "videos:read" ], "x-credit-cost": "none", "x-terminal-states": [ "done", "error" ], "x-cli-command": "faceless renders get", "x-mcp-tool": "faceless_get_render" } }, "/series": { "post": { "operationId": "createSeries", "summary": "Create an automated video series", "description": "Creates a series that automatically generates and posts a new faceless video on a schedule (a set-and-forget channel). Choose a content source and niche or custom prompt, a voice, style and posting cadence; each generated episode charges credits like a single video. The first episode starts generating right after creation. Use GET /series/{id}/episodes to track output, POST /series/{id}/generate to force the next episode now.", "tags": [ "series" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Series name shown in the dashboard" }, "source": { "type": "string", "description": "Content source that scripts every episode, e.g. \"Facts & stories\", \"Reddit post\", \"Custom prompt\". Full list: GET /options?kind=sources" }, "niche": { "type": "string", "description": "Content niche, e.g. scary stories, motivation. Full list: GET /options?kind=niches" }, "customPrompt": { "type": "string", "maxLength": 2000, "description": "Custom topic prompt used instead of (or alongside) a niche" }, "voice": { "type": "string", "description": "TTS voice id for narration. Full list: GET /voices" }, "style": { "type": "string", "description": "Visual style for generated imagery. Full list: GET /options?kind=styles" }, "language": { "type": "string", "description": "Video language, e.g. English. Full list: GET /options?kind=languages" }, "duration": { "type": "string", "enum": [ "30", "60", "90" ], "description": "Target episode length in seconds (30, 60 or 90)" }, "destination": { "type": "string", "description": "Primary auto-post destination platform, e.g. youtube or tiktok" }, "destinationAccounts": { "type": "array", "items": { "type": "string" }, "description": "Connected account ids to auto-post to (from GET /accounts)" }, "generateThumbnails": { "type": "boolean", "description": "Generate 3 AI thumbnail variants for every episode and auto-select the best. Free. Defaults to true." }, "thumbnailSettings": { "type": "object", "properties": { "styleHint": { "type": "string", "maxLength": 200, "description": "Free-text art direction for the thumbnail backgrounds, e.g. \"moody neon, close-up faces\"" } }, "additionalProperties": false, "description": "Thumbnail generation options. Ignored when generateThumbnails is false." }, "autoPostTime": { "type": "string", "description": "Daily auto-post time \"HH:mm\" in the series timezone" }, "postingDays": { "type": "array", "items": { "type": "string" }, "description": "Days of the week to post, e.g. [\"Monday\",\"Wednesday\"]. Omit for every day" }, "timezone": { "type": "string", "description": "IANA timezone for scheduling, e.g. America/New_York" }, "captionStyle": { "type": "string", "description": "Caption theme name. Full list: GET /options?kind=captionThemes" }, "subreddit": { "type": "string", "description": "Subreddit to pull posts from when source is \"Reddit post\"" }, "backgroundVideo": { "type": "string", "description": "Background gameplay/footage id. Full list: GET /options?kind=backgrounds" }, "useRandomBackgroundVideo": { "type": "boolean", "description": "Pick a random background video per episode" }, "layout": { "type": "string", "description": "Video layout variant" }, "brollModel": { "type": "string", "description": "Generation model for visuals: storyboard, motion_lite or motion_pro" }, "showEmojis": { "type": "boolean", "description": "Overlay emojis on captions" }, "enableBackgroundMusic": { "type": "boolean", "description": "Mix background music under the narration" }, "backgroundMusicMood": { "type": "string", "description": "Background music mood. Full list: GET /options?kind=music" }, "hashtags": { "type": "string", "description": "Hashtags appended to post captions" }, "tone": { "type": "string", "description": "Writing tone for generated scripts" }, "youtubePrivacyStatus": { "type": "string", "enum": [ "public", "unlisted", "private" ], "description": "Privacy for auto-posted YouTube videos" } }, "required": [ "name", "source" ], "additionalProperties": false }, "example": { "name": "Deep sea facts", "source": "Facts & stories", "niche": "Ocean facts", "voice": "EXAVITQu4vr4xnSDxMaL", "duration": "60", "autoPostTime": "18:00", "timezone": "America/New_York" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "niche": { "type": "string" }, "createdAt": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e901", "name": "Deep sea facts", "source": "Facts & stories", "niche": "Ocean facts", "createdAt": "2026-07-30T10:00:00.000Z" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "series:write" ], "x-credit-cost": "none at creation; each generated episode charges its model's video cost (20 to 100 credits)", "x-idempotent": true, "x-rate-limit": { "max": 5, "windowSec": 300 }, "x-cli-command": "faceless series create", "x-mcp-tool": "faceless_create_series" }, "get": { "operationId": "listSeries", "summary": "List the team's series", "description": "Returns all automated series for the team with their source, niche, cadence and pause state.", "tags": [ "series" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "niche": { "type": "string" }, "paused": { "type": "boolean" } } } } } }, "example": { "success": true, "data": [ { "id": "665f1b2a9c31a2b3c4d5e901", "name": "Deep sea facts", "source": "Facts & stories", "niche": "Ocean facts", "paused": false } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "series:read" ], "x-credit-cost": "none", "x-cli-command": "faceless series list", "x-mcp-tool": "faceless_list_series" } }, "/series/{id}": { "get": { "operationId": "getSeries", "summary": "Get one series", "description": "Returns a single series with its full configuration: source, niche, voice, style, schedule, destinations and pause state.", "tags": [ "series" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "niche": { "type": "string" }, "voice": { "type": "string" }, "autoPostTime": { "type": "string" }, "paused": { "type": "boolean" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e901", "name": "Deep sea facts", "source": "Facts & stories", "niche": "Ocean facts", "voice": "EXAVITQu4vr4xnSDxMaL", "autoPostTime": "18:00", "paused": false } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "series:read" ], "x-credit-cost": "none", "x-cli-command": "faceless series get", "x-mcp-tool": "faceless_get_series" }, "patch": { "operationId": "updateSeries", "summary": "Update a series", "description": "Updates any subset of a series' configuration (niche, voice, schedule, destinations, pause state and so on). Only the fields you send change.", "tags": [ "series" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Series name shown in the dashboard" }, "source": { "type": "string", "description": "Content source that scripts every episode, e.g. \"Facts & stories\", \"Reddit post\", \"Custom prompt\". Full list: GET /options?kind=sources" }, "niche": { "type": "string", "description": "Content niche, e.g. scary stories, motivation. Full list: GET /options?kind=niches" }, "customPrompt": { "type": "string", "maxLength": 2000, "description": "Custom topic prompt used instead of (or alongside) a niche" }, "voice": { "type": "string", "description": "TTS voice id for narration. Full list: GET /voices" }, "style": { "type": "string", "description": "Visual style for generated imagery. Full list: GET /options?kind=styles" }, "language": { "type": "string", "description": "Video language, e.g. English. Full list: GET /options?kind=languages" }, "duration": { "type": "string", "enum": [ "30", "60", "90" ], "description": "Target episode length in seconds (30, 60 or 90)" }, "destination": { "type": "string", "description": "Primary auto-post destination platform, e.g. youtube or tiktok" }, "destinationAccounts": { "type": "array", "items": { "type": "string" }, "description": "Connected account ids to auto-post to (from GET /accounts)" }, "generateThumbnails": { "type": "boolean", "description": "Generate 3 AI thumbnail variants for every episode and auto-select the best. Free. Defaults to true." }, "thumbnailSettings": { "type": "object", "properties": { "styleHint": { "type": "string", "maxLength": 200, "description": "Free-text art direction for the thumbnail backgrounds, e.g. \"moody neon, close-up faces\"" } }, "additionalProperties": false, "description": "Thumbnail generation options. Ignored when generateThumbnails is false." }, "autoPostTime": { "type": "string", "description": "Daily auto-post time \"HH:mm\" in the series timezone" }, "postingDays": { "type": "array", "items": { "type": "string" }, "description": "Days of the week to post, e.g. [\"Monday\",\"Wednesday\"]. Omit for every day" }, "timezone": { "type": "string", "description": "IANA timezone for scheduling, e.g. America/New_York" }, "captionStyle": { "type": "string", "description": "Caption theme name. Full list: GET /options?kind=captionThemes" }, "subreddit": { "type": "string", "description": "Subreddit to pull posts from when source is \"Reddit post\"" }, "backgroundVideo": { "type": "string", "description": "Background gameplay/footage id. Full list: GET /options?kind=backgrounds" }, "useRandomBackgroundVideo": { "type": "boolean", "description": "Pick a random background video per episode" }, "layout": { "type": "string", "description": "Video layout variant" }, "brollModel": { "type": "string", "description": "Generation model for visuals: storyboard, motion_lite or motion_pro" }, "showEmojis": { "type": "boolean", "description": "Overlay emojis on captions" }, "enableBackgroundMusic": { "type": "boolean", "description": "Mix background music under the narration" }, "backgroundMusicMood": { "type": "string", "description": "Background music mood. Full list: GET /options?kind=music" }, "hashtags": { "type": "string", "description": "Hashtags appended to post captions" }, "tone": { "type": "string", "description": "Writing tone for generated scripts" }, "youtubePrivacyStatus": { "type": "string", "enum": [ "public", "unlisted", "private" ], "description": "Privacy for auto-posted YouTube videos" }, "paused": { "type": "boolean", "description": "Pause or resume automatic episode generation" } }, "additionalProperties": false }, "example": { "autoPostTime": "09:00", "paused": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "autoPostTime": { "type": "string" }, "paused": { "type": "boolean" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5e901", "name": "Deep sea facts", "autoPostTime": "09:00", "paused": false } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "series:write" ], "x-credit-cost": "none", "x-cli-command": "faceless series update", "x-mcp-tool": "faceless_update_series" }, "delete": { "operationId": "deleteSeries", "summary": "Delete a series", "description": "Deletes a series and stops all future automatic generation. Already-generated videos are kept.", "tags": [ "series" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } }, "example": { "success": true, "data": { "deleted": true } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "series:write" ], "x-credit-cost": "none", "x-cli-command": "faceless series delete", "x-mcp-tool": "faceless_delete_series" } }, "/series/{id}/generate": { "post": { "operationId": "generateSeriesEpisode", "summary": "Generate the next episode now", "description": "Immediately generates the next episode of a series instead of waiting for its schedule. Charges the series' per-episode credit cost. The episode appears in GET /series/{id}/episodes; poll the created video's status like any other video.", "tags": [ "series" ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "projectId": { "type": "string" }, "statusUrl": { "type": "string" } } } } }, "example": { "success": true, "data": { "projectId": "665f1b2a9c31a2b3c4d5ea01", "statusUrl": "/api/v1/videos/665f1b2a9c31a2b3c4d5ea01/status" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "series:write" ], "x-credit-cost": "the series' per-episode video cost (20 to 100 credits depending on model)", "x-idempotent": true, "x-rate-limit": { "max": 5, "windowSec": 300 }, "x-cli-command": "faceless series generate", "x-mcp-tool": "faceless_generate_series_episode" } }, "/series/{id}/episodes": { "get": { "operationId": "listSeriesEpisodes", "summary": "List a series' episodes", "description": "Returns the videos generated by a series, newest first, with their generation status, scheduled post time and posted state.", "tags": [ "series" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, starting at 1" }, "description": "Page number, starting at 1" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Items per page (max 100)" }, "description": "Items per page (max 100)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "status": { "type": "string" }, "scheduledTime": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" } } } } }, "example": { "success": true, "data": [ { "id": "665f1b2a9c31a2b3c4d5eb01", "projectId": "665f1b2a9c31a2b3c4d5ea01", "status": "posted", "scheduledTime": "2026-07-30T18:00:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 1 } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "series:read" ], "x-credit-cost": "none", "x-cli-command": "faceless series episodes", "x-mcp-tool": "faceless_list_series_episodes" } }, "/posts": { "post": { "operationId": "publishPost", "summary": "Publish a rendered video to a platform now", "description": "Immediately publishes a rendered video to one connected platform (youtube, tiktok, instagram, x, facebook, linkedin or threads). The video must be rendered first (renderedVideoUrl present, or pass videoUrl explicitly) and the team must have that platform connected (GET /accounts). For future-dated posting use POST /posts/schedule instead.", "tags": [ "posts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The video (project) to publish" }, "platform": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "x", "facebook", "linkedin", "threads" ], "description": "Destination platform; must be connected (see GET /accounts)" }, "title": { "type": "string", "maxLength": 2200, "description": "Post title or caption (platform-appropriate); falls back to the video's stored post metadata" }, "description": { "type": "string", "maxLength": 5000, "description": "Longer description for platforms that support one (YouTube, Facebook, LinkedIn)" }, "privacyStatus": { "type": "string", "enum": [ "public", "unlisted", "private" ], "description": "YouTube only; defaults to public" }, "authId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Specific connected account id when the team has several for the platform (from GET /accounts)" } }, "required": [ "videoId", "platform" ], "additionalProperties": false }, "example": { "videoId": "665f1b2a9c31a2b3c4d5e801", "platform": "youtube", "title": "The ocean has rivers underwater" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "platform": { "type": "string" }, "videoId": { "type": "string" }, "postUrl": { "type": "string" } } } } }, "example": { "success": true, "data": { "platform": "youtube", "videoId": "665f1b2a9c31a2b3c4d5e801", "postUrl": "https://youtube.com/shorts/dQw4w9WgXcQ" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "posts:write" ], "x-credit-cost": "none", "x-idempotent": true, "x-rate-limit": { "max": 10, "windowSec": 300 }, "x-cli-command": "faceless posts publish", "x-mcp-tool": "faceless_publish_post" } }, "/posts/schedule": { "post": { "operationId": "schedulePost", "summary": "Schedule a video to one or more platforms", "description": "Schedules a video to be rendered (if needed) and posted to multiple platforms at a future time. Every platform in the list must have its post metadata already set on the video (PATCH /videos/{id}); the request is rejected otherwise. Cancel with DELETE /posts/{videoId}. See the posting calendar with GET /calendar.", "tags": [ "posts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "videoId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The video (project) to schedule" }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "x", "facebook", "linkedin", "threads" ] }, "minItems": 1, "description": "Platforms to post to; each needs its post metadata set on the video first" }, "scheduledTime": { "type": "string", "description": "When to post (ISO 8601, future)" } }, "required": [ "videoId", "platforms", "scheduledTime" ], "additionalProperties": false }, "example": { "videoId": "665f1b2a9c31a2b3c4d5e801", "platforms": [ "youtube", "tiktok" ], "scheduledTime": "2026-08-01T18:00:00Z" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "taskId": { "type": "string" }, "platforms": { "type": "array", "items": { "type": "string" } }, "scheduledTime": { "type": "string" } } } } }, "example": { "success": true, "data": { "taskId": "665f1b2a9c31a2b3c4d5ec01", "platforms": [ "youtube", "tiktok" ], "scheduledTime": "2026-08-01T18:00:00Z" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "posts:write" ], "x-credit-cost": "none", "x-idempotent": true, "x-rate-limit": { "max": 20, "windowSec": 300 }, "x-cli-command": "faceless posts schedule", "x-mcp-tool": "faceless_schedule_post" } }, "/posts/{id}": { "delete": { "operationId": "cancelPost", "summary": "Cancel a scheduled post", "description": "Cancels the pending scheduled posting for a video (the id is the video id used in POST /posts/schedule). Posts that already went out are not affected.", "tags": [ "posts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "cancelled": { "type": "boolean" } } } } }, "example": { "success": true, "data": { "cancelled": true } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "posts:write" ], "x-credit-cost": "none", "x-cli-command": "faceless posts cancel", "x-mcp-tool": "faceless_cancel_post" } }, "/calendar": { "get": { "operationId": "getCalendar", "summary": "Posting calendar", "description": "Returns the team's social posts (scheduled, posted and failed) within a date range, across all platforms. Use it to see what is queued before scheduling more.", "tags": [ "posts" ], "parameters": [ { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "description": "Range start (inclusive)" }, "description": "Range start (inclusive)" }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "description": "Range end (inclusive)" }, "description": "Range end (inclusive)" }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "x", "facebook", "linkedin", "threads" ], "description": "Filter to one platform" }, "description": "Filter to one platform" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by post status, e.g. scheduled, posted, failed" }, "description": "Filter by post status, e.g. scheduled, posted, failed" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "platform": { "type": "string" }, "status": { "type": "string" }, "scheduledTime": { "type": "string" } } } } } }, "example": { "success": true, "data": [ { "id": "665f1b2a9c31a2b3c4d5ed01", "projectId": "665f1b2a9c31a2b3c4d5e801", "platform": "youtube", "status": "scheduled", "scheduledTime": "2026-08-01T18:00:00.000Z" } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "posts:read" ], "x-credit-cost": "none", "x-cli-command": "faceless calendar", "x-mcp-tool": "faceless_get_calendar" } }, "/accounts": { "get": { "operationId": "listAccounts", "summary": "List connected social accounts", "description": "Returns the social accounts connected to the team (YouTube, TikTok, Instagram, X, Facebook, LinkedIn, Threads) with their ids. Use the ids as authId in publishPost and destinationAccounts in series. Connecting accounts itself happens in the dashboard (OAuth), not over the API.", "tags": [ "accounts" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "youtube": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "channelName": { "type": "string" } } } }, "tiktok": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "status": { "type": "string" } } } }, "instagram": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "status": { "type": "string" } } } } } } } }, "example": { "success": true, "data": { "youtube": [ { "id": "665f1b2a9c31a2b3c4d5ee01", "channelName": "Deep Sea Facts" } ], "tiktok": [ { "id": "665f1b2a9c31a2b3c4d5e901", "username": "mychannel", "status": "connected" } ], "instagram": [ { "id": "665f1b2a9c31a2b3c4d5e902", "username": "mychannel", "status": "connected" } ] } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "accounts:read" ], "x-credit-cost": "none", "x-cli-command": "faceless accounts", "x-mcp-tool": "faceless_list_accounts" } }, "/voices": { "get": { "operationId": "listVoices", "summary": "List TTS voices", "description": "Returns the text-to-speech voices available for narration, including the team's custom cloned voices and Recommended Studio Quality voices. Recommended ids are opaque: pass the returned id unchanged and Faceless will resolve the appropriate ElevenLabs model. Use a voice's id as voiceId in createVideo or voice in createSeries.", "tags": [ "catalog" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "baseVoiceId": { "type": "string" }, "name": { "type": "string" }, "previewUrl": { "type": "string" }, "labels": { "type": "object", "properties": { "language": { "type": "string" }, "gender": { "type": "string" }, "accent": { "type": "string" } } }, "isCustom": { "type": "boolean" }, "isRecommended": { "type": "boolean" }, "qualityTier": { "type": "string" }, "modelPolicy": { "type": "string" }, "targetLanguages": { "type": "array", "items": { "type": "string" } } } } } } }, "example": { "success": true, "data": [ { "id": "eleven_quality:EXAVITQu4vr4xnSDxMaL", "baseVoiceId": "EXAVITQu4vr4xnSDxMaL", "name": "Sarah - Studio Quality", "previewUrl": "https://storage.googleapis.com/eleven-public-prod/premade/voices/EXAVITQu4vr4xnSDxMaL.mp3", "labels": { "language": "en", "gender": "female", "accent": "american" }, "isCustom": false, "isRecommended": true, "qualityTier": "studio", "modelPolicy": "quality_auto", "targetLanguages": [ "en" ] } ] } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "catalog:read" ], "x-credit-cost": "none", "x-cli-command": "faceless voices", "x-mcp-tool": "faceless_list_voices" } }, "/options": { "get": { "operationId": "listOptions", "summary": "List content option catalogs", "description": "Enumerates the option catalogs used by createVideo and createSeries: sources, styles, niches, languages, durations, models (with credit costs), captionThemes, music moods, background videos and example subreddits. Call without kind to list the available kinds; pass kind to get that catalog's items.", "tags": [ "catalog" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sources", "styles", "niches", "languages", "durations", "models", "captionThemes", "music", "backgrounds", "subreddits" ], "description": "Which catalog to return; omit to list available kinds" }, "description": "Which catalog to return; omit to list available kinds" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "kind": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "name": { "type": "string" }, "credits": { "type": "integer" } } } } } } } }, "example": { "success": true, "data": { "kind": "models", "items": [ { "value": "storyboard", "name": "Faceless Storyboard", "credits": 20 } ] } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "catalog:read" ], "x-credit-cost": "none", "x-cli-command": "faceless options", "x-mcp-tool": "faceless_list_options" } }, "/assets": { "post": { "operationId": "createAsset", "summary": "Register a media asset by URL", "description": "Registers an already-hosted media file (video, image or audio URL) as a team asset usable in projects. This endpoint takes a URL, not raw bytes; host the file anywhere public (or use the dashboard for direct uploads).", "tags": [ "assets" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Public URL of the media file" }, "name": { "type": "string", "maxLength": 120, "description": "Display name for the asset" }, "fileType": { "type": "string", "description": "MIME type hint, e.g. video/mp4" } }, "required": [ "url" ], "additionalProperties": false }, "example": { "url": "https://example.com/broll.mp4", "name": "Intro b-roll" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" } } } } }, "example": { "success": true, "data": { "id": "665f1b2a9c31a2b3c4d5ef01", "url": "https://example.com/broll.mp4", "name": "Intro b-roll" } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "assets:write" ], "x-credit-cost": "none", "x-idempotent": true, "x-cli-command": "faceless assets create", "x-mcp-tool": "faceless_create_asset" } }, "/analytics": { "get": { "operationId": "getAnalytics", "summary": "Cross-platform posting analytics", "description": "Returns aggregated performance for the team's published posts (views, likes, comments and posting volume) across YouTube, TikTok, Instagram and Facebook, over a trailing window.", "tags": [ "analytics" ], "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "youtube", "tiktok", "instagram", "facebook" ], "description": "Filter to one platform" }, "description": "Filter to one platform" }, { "name": "authId", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "Filter to one connected account" }, "description": "Filter to one connected account" }, { "name": "range", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Trailing window in days (default 30)" }, "description": "Trailing window in days (default 30)" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "totals": { "type": "object", "properties": { "posts": { "type": "integer" }, "views": { "type": "integer" }, "likes": { "type": "integer" } } }, "platforms": { "type": "object", "properties": { "youtube": { "type": "object", "properties": { "posts": { "type": "integer" }, "views": { "type": "integer" } } } } } } } } }, "example": { "success": true, "data": { "totals": { "posts": 42, "views": 128530, "likes": 9210 }, "platforms": { "youtube": { "posts": 20, "views": 88000 } } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scopes": [ "analytics:read" ], "x-credit-cost": "none", "x-cli-command": "faceless analytics", "x-mcp-tool": "faceless_get_analytics" } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer fl_live_..." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_input", "unauthorized", "forbidden_scope", "not_found", "conflict", "insufficient_credits", "usage_limit_reached", "rate_limited", "internal_error" ] }, "message": { "type": "string" } } } } } } }, "x-scopes": [ "credits:read", "videos:read", "videos:write", "series:read", "series:write", "posts:read", "posts:write", "accounts:read", "assets:read", "assets:write", "analytics:read", "catalog:read" ] }