{ "openapi": "3.1.0", "info": { "title": "SeedViral API", "version": "v1 (connector 1.0.0)", "summary": "Make and manage short videos from your own agent or server.", "description": "SeedViral is a short video studio for TikTok, Reels and YouTube Shorts. It makes narrated faceless video series, one-off videos, short dramas, presenter videos, product ads, music videos and clips from long videos. Plans are per series, and every paid plan includes monthly credits for extra videos.\n\nVideos made through the API are paid for with the workspace's plan credits (Hobby $29/month: 100 credits a month; Daily $59/month: 250 credits a month; Pro $97/month: 500 credits a month). One video, 30 to 40 seconds: 10 credits; One video, 60 to 70 seconds: 15 credits.\n\nCheck the price, then confirm: POST /api/v1/videos/quotes returns the exact credits and charges nothing; POST /api/v1/videos with the quote id and an Idempotency-Key spends them. Ask your human before accepting a quote.\n\nNo key can change billing or plans, connect or post to social accounts, manage the account or use a real person's face or voice. Limits per workspace per hour: 1,200 reads, 300 writes. Full reference: https://seedviral.com/agent/1.0.0/README.md.", "contact": { "name": "SeedViral support", "email": "support@seedviral.com", "url": "https://seedviral.com/support" }, "termsOfService": "https://seedviral.com/terms" }, "externalDocs": { "description": "SeedViral for agents", "url": "https://seedviral.com/agents" }, "servers": [ { "url": "https://seedviral.com" } ], "tags": [ { "name": "Account", "description": "The key's workspace, the catalog and credits." }, { "name": "Series", "description": "Series drafts and their topic sources." }, { "name": "Videos", "description": "Quote, make, follow and download videos." } ], "paths": { "/api/v1/webhooks": { "get": { "summary": "List webhook subscriptions", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Agents" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object" } } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } }, "post": { "summary": "Create a signed webhook subscription", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "enum": [ "video.ready", "video.failed", "drama.ready" ] } } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } }, "delete": { "summary": "Revoke a webhook subscription", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/actions/{action}": { "post": { "summary": "Agent studio action: dramas, music, clips, voice changes, edit quotes and research", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Agents" ], "parameters": [ { "name": "action", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/workspace": { "get": { "summary": "The key's workspace and permissions", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Account" ], "operationId": "getWorkspace", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string" }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "create" ] } } }, "required": [] } }, "required": [] } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/catalog": { "get": { "summary": "Formats, niches, languages, voices, art and caption styles, lengths and credit costs", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Account" ], "operationId": "getCatalog", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/balance": { "get": { "summary": "Credits available and reserved", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Account" ], "operationId": "getBalance", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/series": { "get": { "summary": "List series", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Series" ], "operationId": "listSeries", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "From the previous page's nextCursor." }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": "array", "items": { "$ref": "#/components/schemas/Series" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } }, "post": { "summary": "Create a series draft (no plan, review mode, no destinations)", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Series" ], "operationId": "createSeries", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/SeriesSettings" } }, "required": [ "settings" ], "additionalProperties": false }, { "type": "object", "properties": { "draft": { "$ref": "#/components/schemas/Draft" } }, "required": [ "draft" ], "additionalProperties": false } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "$ref": "#/components/schemas/Series" } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/series/{seriesId}": { "get": { "summary": "Get a series", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Series" ], "operationId": "getSeries", "parameters": [ { "name": "seriesId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "$ref": "#/components/schemas/Series" } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } }, "put": { "summary": "Update a series draft; publishing settings are kept", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Series" ], "operationId": "updateSeries", "parameters": [ { "name": "seriesId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/SeriesSettings" }, "expectedRevision": { "type": "integer" } }, "required": [ "settings", "expectedRevision" ], "additionalProperties": false }, { "type": "object", "properties": { "draft": { "$ref": "#/components/schemas/Draft" }, "expectedRevision": { "type": "integer" } }, "required": [ "draft", "expectedRevision" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "$ref": "#/components/schemas/Series" } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/series/{seriesId}/topics": { "get": { "summary": "A series' topic source, queue and history", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Series" ], "operationId": "getTopics", "parameters": [ { "name": "seriesId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topics" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } }, "post": { "summary": "Preview, use, add, pause, resume, remove, skip, requeue or check topics", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Series" ], "operationId": "changeTopics", "parameters": [ { "name": "seriesId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "description": "Required for `use` and `add`." } ], "description": "CSV bodies may be up to 1.2 MB. `use` and `add` need an Idempotency-Key.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "const": "preview" }, "kind": { "type": "string", "enum": [ "rss", "youtube", "csv" ] }, "input": { "description": "A link for rss/youtube; {fileName, text, mapping?} for csv." } }, "required": [ "action", "kind", "input" ] }, { "type": "object", "properties": { "action": { "const": "use" }, "kind": { "type": "string", "enum": [ "rss", "youtube", "csv" ] }, "input": {}, "expectedSourceId": { "type": [ "string", "null" ] }, "previewHash": { "type": "string" } }, "required": [ "action", "kind", "input", "expectedSourceId" ] }, { "type": "object", "properties": { "action": { "const": "add" }, "title": { "type": "string" }, "notes": { "type": "string" }, "link": { "type": "string", "format": "uri" } }, "required": [ "action", "title" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "pause", "resume", "remove" ] }, "sourceId": { "type": "string" } }, "required": [ "action", "sourceId" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "skip", "requeue" ] }, "itemId": { "type": "string" } }, "required": [ "action", "itemId" ] }, { "type": "object", "properties": { "action": { "const": "check" } }, "required": [ "action" ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topics" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/videos/quotes": { "post": { "summary": "Quote one video: exact credits and the frozen settings. Charges nothing.", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Videos" ], "operationId": "quoteVideo", "description": "Quotes last 15 minutes and make at most one video. A link is read now, once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/Quote" } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/videos": { "get": { "summary": "List videos, newest first", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Videos" ], "operationId": "listVideos", "parameters": [ { "name": "seriesId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "From the previous page's nextCursor." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "videos": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } }, "post": { "summary": "Accept a quote: spends its credits and starts the video", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Videos" ], "operationId": "createVideo", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string" } }, "required": [ "quoteId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "video": { "type": "object", "properties": { "id": { "type": "string" }, "credits": { "type": "integer" }, "quoteId": { "type": "string" }, "state": { "type": "string" } }, "required": [] } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/videos/{videoId}": { "get": { "summary": "Get a video", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Videos" ], "operationId": "getVideo", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "video": { "$ref": "#/components/schemas/Video" } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/videos/{videoId}/versions": { "get": { "summary": "Saved versions of a video", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Videos" ], "operationId": "listVideoVersions", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "From the previous page's nextCursor." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/videos/{videoId}/download": { "get": { "summary": "A short-lived download link (fetch it without the key)", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Videos" ], "operationId": "getDownloadLink", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "integer" }, "thumbnailUrl": { "type": [ "string", "null" ] } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "410": { "$ref": "#/components/responses/E410" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api/v1/videos/{videoId}/exports": { "get": { "summary": "Square and landscape copies of a video", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "read", "tags": [ "Videos" ], "operationId": "listExports", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "aspect": { "type": "string" }, "state": { "type": "string" }, "downloadUrl": { "type": [ "string", "null" ] } }, "required": [] } } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } }, "post": { "summary": "Request a square or landscape copy (free)", "security": [ { "apiKey": [] } ], "x-seedviral-permission": "create", "tags": [ "Videos" ], "operationId": "requestExport", "parameters": [ { "name": "videoId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "aspect": { "type": "string", "enum": [ "1:1", "16:9" ] } }, "required": [ "aspect" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "export": { "type": "object", "additionalProperties": true } }, "required": [] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "410": { "$ref": "#/components/responses/E410" }, "413": { "$ref": "#/components/responses/E413" }, "415": { "$ref": "#/components/responses/E415" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "503": { "$ref": "#/components/responses/E503" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "svk__", "description": "Create a key at https://seedviral.com/developers. Permissions: read (every key), create (drafts, topics, quotes, videos, copies)." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{8,128}$" }, "description": "Bound to the complete request. The same key and body returns the stored response (Idempotent-Replayed: true)." } }, "responses": { "E400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "Missing, invalid or expired key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E402": { "description": "Not enough credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "The key's permission does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflict (idempotency, revision or plan); see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E410": { "description": "Expired quote or deleted workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E413": { "description": "Body too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "A source or link could not be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "Unavailable; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "API_KEY_REQUIRED", "INVALID_API_KEY", "KEY_EXPIRED", "SCOPE_REQUIRED", "WORKSPACE_DELETED", "RATE_LIMITED", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_IN_PROGRESS", "QUOTE_NOT_FOUND", "QUOTE_EXPIRED", "SERIES_NOT_FOUND", "SERIES_ARCHIVED", "FORMAT_NEEDS_LONG", "INVALID_STYLE", "PREVIEW_CHANGED", "INVALID_CSV_MAPPING", "INSUFFICIENT_CREDITS", "REQUEST_TOO_LARGE", "INVALID_REQUEST", "INVALID_SETTINGS", "INVALID_DRAFT", "INVALID_SERIES", "INVALID_PREMISE", "INVALID_REQUEST_ID", "GENERATION_UNAVAILABLE", "NOT_FOUND" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Catalog": { "type": "object", "properties": { "formats": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "niches": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "languages": { "type": "array", "items": {} }, "voices": { "type": "array", "items": {} }, "artStyles": { "type": "array", "items": {} }, "captionStyles": { "type": "array", "items": {} }, "durations": { "type": "array", "items": {} }, "cadences": { "type": "array", "items": {} }, "credits": { "type": "object", "additionalProperties": true }, "counts": { "type": "object", "additionalProperties": true, "description": "Live number of formats, niches, languages, voices, art styles and caption styles." } }, "required": [] }, "Balance": { "type": "object", "properties": { "available": { "type": "integer" }, "reserved": { "type": "integer" }, "plan": {}, "hasPlan": { "type": "boolean" } }, "required": [] }, "SeriesSettings": { "type": "object", "properties": { "topic": { "type": "string", "description": "What the series is about in plain words, or a niche name. Needed on create unless niche is given." }, "niche": { "type": "string" }, "brief": { "type": "string" }, "name": { "type": "string", "maxLength": 80 }, "language": { "type": "string", "default": "English" }, "voice": { "type": "string", "description": "Voice name such as Dramatic, or a voice id from the catalog." }, "artStyle": { "type": "string", "default": "Cinematic" }, "captionStyle": { "type": "string", "default": "Clean" }, "music": { "type": "string", "default": "none" }, "duration": { "type": "string", "enum": [ "30-40", "60-70" ], "default": "30-40" }, "cadence": { "type": "string", "enum": [ "3/week", "1/day", "2/day" ], "default": "3/week" }, "postingTime": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "default": "18:00" }, "secondPostingTime": { "type": "string" }, "timezone": { "type": "string", "default": "Europe/London" }, "format": { "type": "string" }, "reviewScripts": { "type": "boolean", "default": false } }, "required": [], "additionalProperties": false, "description": "The simple series form. Missing values get catalog defaults; an unknown value is 400 INVALID_SETTINGS listing the valid options." }, "Draft": { "type": "object", "additionalProperties": true, "description": "The full studio draft (advanced; prefer SeriesSettings). Valid values come from GET /api/v1/catalog. Publishing fields are ignored." }, "Series": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "state": { "type": "string" }, "revision": { "type": "integer" }, "draft": { "$ref": "#/components/schemas/Draft" }, "nextSlotAt": { "type": [ "integer", "null" ] }, "blockers": { "type": "array", "items": {} } }, "required": [], "additionalProperties": true }, "Topics": { "type": "object", "properties": { "source": {}, "queue": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "queued": { "type": "integer" }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "waitingSince": {}, "queueLimit": { "type": "integer" } }, "required": [], "additionalProperties": true }, "Style": { "oneOf": [ { "type": "object", "properties": { "from": { "const": "series" }, "seriesId": { "type": "string" } }, "required": [ "from", "seriesId" ] }, { "type": "object", "properties": { "from": { "const": "custom" }, "art": { "type": "string" }, "voice": { "type": "string" }, "caption": { "type": "string" }, "language": { "type": "string" } }, "required": [ "from", "art", "voice", "caption", "language" ] } ] }, "QuoteRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "prompt", "script", "link", "remix" ] }, "text": { "type": "string", "description": "prompt: 8 to 1,000 characters; script: 40 to 4,000; remix: up to 600." }, "link": { "type": "string", "format": "uri", "maxLength": 2048 }, "duration": { "type": "string", "enum": [ "30–40", "60–70" ], "description": "Length in seconds (en dash)." }, "style": { "$ref": "#/components/schemas/Style" }, "format": { "type": "string", "description": "A format id from the catalog; empty for an original story." }, "gameplay": { "type": "string", "description": "A background loop, only with a gameplay format." }, "transcript": { "type": "string", "maxLength": 3400, "description": "remix only." }, "remix": { "type": "string", "enum": [ "like", "part2" ] } }, "required": [ "mode", "duration", "style" ] }, "Quote": { "type": "object", "properties": { "id": { "type": "string" }, "credits": { "type": "integer" }, "expiresAt": { "type": "integer" }, "balance": { "type": [ "integer", "null" ] }, "input": { "type": "object", "additionalProperties": true }, "settings": { "type": "object", "additionalProperties": true } }, "required": [] }, "Video": { "type": "object", "properties": { "id": { "type": "string" }, "stage": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "scheduledFor": {}, "readyAt": {}, "failure": {} }, "required": [], "additionalProperties": true } } } }