{ "openapi": "3.1.0", "info": { "title": "Vuesy API", "version": "1.0.0", "description": "Create AI documentary videos from a script or your own voiceover, write scripts and thumbnails, and export MP4s — with the same credits as the Vuesy studio. Docs: https://vuesy-app-test.684108.xyz/developers" }, "servers": [ { "url": "https://vuesy-app-test.684108.xyz" } ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer vuesy_…" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "What went wrong, readable" }, "code": { "type": "string", "description": "A stable code when there is one" } }, "required": [ "error" ] }, "Credits": { "type": "object", "properties": { "balance": { "type": "integer" }, "held": { "type": "integer", "description": "Held by jobs in progress" }, "available": { "type": "integer" }, "expires_at": { "type": "integer" }, "topup_credits": { "type": "integer" }, "renews_at": { "type": "integer" }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "max_credits_day": { "type": "integer" }, "spent_today": { "type": "integer" } } } } }, "CreditsHistory": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "integer" }, "type": { "enum": [ "credit", "debit", "hold", "settle", "refund", "clawback", "expire" ] }, "credits": { "type": "integer" }, "balance_after": { "type": "integer" }, "job_id": { "type": "string", "nullable": true } } } } } }, "Account": { "type": "object", "properties": { "object": { "type": "string", "const": "account" }, "plan": { "type": "string" }, "custom_limits": { "type": "boolean" }, "limits": { "type": "object", "properties": { "active_keys_per_account": { "type": "integer" }, "paid_requests_per_minute_per_account": { "type": "integer" }, "requests_per_minute_per_account": { "type": "integer" }, "requests_per_minute_per_key": { "type": "integer" }, "scripts_and_thumbnails_in_progress_per_account": { "type": "integer" }, "videos_in_progress_per_account": { "type": "integer" }, "videos_per_day_per_account": { "type": "integer" }, "videos_per_day_per_key": { "type": "integer" } } }, "usage": { "type": "object", "properties": { "videos_today": { "type": "integer" }, "videos_in_progress": { "type": "integer" }, "resets_at": { "type": "integer" } } }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "max_credits_day": { "type": "integer" }, "credits_spent_today": { "type": "integer" }, "videos_today": { "type": "integer" }, "videos_in_progress": { "type": "integer" } } } } }, "Quote": { "type": "object", "properties": { "duration_sec": { "type": "integer" }, "lang": { "type": "string" }, "voice": { "type": "string", "nullable": true }, "quality": { "enum": [ "standard", "high" ] }, "cost_credits": { "type": "integer" } } }, "Languages": { "type": "object", "properties": { "languages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "model": { "type": "string" }, "chars_per_min": { "type": "integer" }, "quality": { "enum": [ "standard", "high" ] } } } } } }, "Voices": { "type": "object", "properties": { "lang": { "type": "string" }, "voices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "gender": { "type": "string" }, "age": { "type": "string" }, "style": { "type": "string" }, "region": { "type": "string" }, "model": { "type": "string" }, "sample_url": { "type": "string" }, "quality": { "enum": [ "standard", "high" ] } } } } } }, "Music": { "type": "object", "properties": { "catalog": { "type": "array", "items": { "type": "object", "properties": { "mood": { "type": "string" }, "label": { "type": "string" }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string" }, "title": { "type": "string" }, "artist": { "type": "string" }, "duration": { "type": "number" } } } } } } } } }, "Progress": { "type": "object", "properties": { "percent": { "type": "number" }, "phase": { "type": "string" }, "eta_s": { "type": "integer", "description": "Seconds left (estimate)", "nullable": true } }, "nullable": true }, "Video": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "video" }, "status": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "interrupted" ] }, "progress": { "$ref": "#/components/schemas/Progress" }, "queue_position": { "type": "integer", "nullable": true }, "project_id": { "type": "string", "nullable": true }, "cost_credits": { "type": "integer", "description": "Held while it runs, charged when it succeeds" }, "refunded": { "type": "boolean", "description": "The credits came back (failed or cancelled)" }, "estimated_duration_sec": { "type": "number", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } }, "required": [ "id", "object", "status" ] }, "Export": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "export" }, "status": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "interrupted" ] }, "progress": { "$ref": "#/components/schemas/Progress" }, "queue_position": { "type": "integer", "nullable": true }, "project_id": { "type": "string" }, "cost_credits": { "type": "integer", "description": "0 for the first export of a video, else 4" }, "refunded": { "type": "boolean" }, "download_filename": { "type": "string", "nullable": true }, "download_url": { "type": "string", "description": "The MP4 once succeeded (re-signed on every GET, no key needed)", "nullable": true }, "download_url_expires_in_s": { "type": "integer", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "error": { "type": "string", "nullable": true }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } }, "required": [ "id", "object", "status" ] }, "List": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": {} }, "has_more": { "type": "boolean" }, "next_starting_after": { "type": "string", "nullable": true } } }, "Upload": { "type": "object", "properties": { "object": { "type": "string", "const": "upload" }, "kind": { "enum": [ "audio", "music" ] }, "key": { "type": "string" }, "put_url": { "type": "string" }, "method": { "type": "string", "const": "PUT" }, "expires_in_s": { "type": "integer" }, "max_bytes": { "type": "integer" } } }, "ScriptUpload": { "type": "object", "properties": { "key": { "type": "string" }, "chars": { "type": "integer" } } }, "References": { "type": "object", "properties": { "object": { "type": "string", "const": "references" }, "type": { "enum": [ "channel", "video" ] }, "sort": { "enum": [ "recent", "popular" ] }, "videos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "thumbnail_url": { "type": "string", "nullable": true }, "duration_sec": { "type": "integer" }, "views": { "type": "integer" } } } }, "credits": { "type": "object", "properties": { "script": { "type": "integer" }, "thumbnail": { "type": "integer" } } }, "included_in_plan_left": { "type": "object", "properties": { "scripts": { "type": "integer" }, "thumbnails": { "type": "integer" } } } } }, "Task": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "enum": [ "script", "thumbnail" ] }, "status": { "enum": [ "running", "succeeded", "failed" ] }, "result": { "oneOf": [ { "type": "object", "properties": { "title": { "type": "string" }, "script": { "type": "string" }, "words": { "type": "integer" } } }, { "type": "object", "properties": { "image_url": { "type": "string", "description": "7-day link" }, "text": { "type": "string" } } } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "references_source": { "enum": [ "channel", "videos", "topic_search" ], "nullable": true }, "created_at": { "type": "integer" }, "updated_at": { "type": "integer" } }, "required": [ "id", "status" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "nullable": true }, "status": { "enum": [ "enabled", "disabled" ] }, "disabled_reason": { "type": "string", "nullable": true }, "failed_in_a_row": { "type": "integer" }, "last_success_at": { "type": "integer" }, "last_failure_at": { "type": "integer" }, "created_at": { "type": "integer" }, "secret": { "type": "string", "description": "Shown on create and rotate-secret only" } } }, "Delivery": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…" }, "object": { "type": "string", "const": "webhook_delivery" }, "type": { "type": "string" }, "object_id": { "type": "string" }, "status": { "enum": [ "pending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "last_status_code": { "type": "integer" }, "last_error": { "type": "string" }, "next_attempt_at": { "type": "integer" }, "delivered_at": { "type": "integer" }, "created_at": { "type": "integer" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "evt_…, also in Vuesy-Event-Id" }, "object": { "type": "string", "const": "event" }, "type": { "type": "string" }, "api_version": { "type": "string" }, "created_at": { "type": "integer" }, "data": { "type": "object", "properties": { "object": { "oneOf": [ { "$ref": "#/components/schemas/Video" }, { "$ref": "#/components/schemas/Export" }, { "$ref": "#/components/schemas/Task" } ] } } } } } } }, "paths": { "/v1/videos": { "post": { "summary": "Create a video", "tags": [ "Videos" ], "x-vuesy-scope": "videos:write", "x-vuesy-credits": "video price (GET /v1/quote)", "description": "Charges the video price when accepted (refunded if it fails). Poll GET /v1/videos/{id}.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" }, "description": "Any unique string per new request. Retrying with the same key and body returns the same object (never charges twice)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "script": { "type": "string", "description": "The narration text (TTS voice). One of script, script_key, audio_key.", "maxLength": 50000 }, "script_key": { "type": "string", "description": "Key from POST /v1/uploads/script (for long scripts)." }, "audio_key": { "type": "string", "description": "Key from POST /v1/uploads with kind=audio: your own voiceover (no TTS)." }, "duration_sec": { "type": "integer", "description": "Not needed: a script is priced by its length and your own audio by the length our server measured when you uploaded it.", "minimum": 1, "maximum": 5400 }, "lang": { "type": "string", "description": "Language code from GET /v1/languages, or auto. Default en (script) / auto (audio)." }, "voice": { "type": "string", "description": "Voice id from GET /v1/voices (script videos only)." }, "title": { "type": "string", "maxLength": 150 }, "subtitles": { "type": "boolean", "default": true }, "animations": { "type": "boolean", "default": true }, "background": { "type": "string", "description": "blue (default), cinematic, vintage, light or grid" }, "no_music": { "type": "boolean", "default": false }, "music_volume": { "type": "number", "description": "Background music volume; above 0.2 plays at 0.2.", "minimum": 0, "maximum": 1, "default": 0.03 }, "music_style": { "enum": [ "epic", "documentary", "tension", "sad", "chill", "upbeat" ] }, "music_track": { "type": "string", "description": "'/.mp3' from GET /v1/music" }, "music_key": { "type": "string", "description": "Key from POST /v1/uploads with kind=music: your own background track." }, "max_cost_credits": { "type": "integer", "description": "Refuse (422) if the video would cost more; never charged above it. Not with audio_key.", "minimum": 1, "maximum": 100000 }, "options": { "type": "object", "description": "Same fields nested (accepted for web-body compatibility)." }, "external_id": { "type": "string", "description": "Your own order or customer id: 1-128 printable ASCII characters, no spaces. Filter lists with ?external_id=." }, "metadata": { "type": "object", "description": "Your own data, echoed on the object and on webhooks: up to 20 keys [A-Za-z0-9_.-]{1,40}, string values up to 500 characters (numbers become strings), 8 KB in total." } } } } } }, "responses": { "200": { "description": "Replay of the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List videos (newest first)", "tags": [ "Videos" ], "x-vuesy-scope": "videos:read", "x-vuesy-credits": "free", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "status", "in": "query", "schema": { "enum": [ "queued", "running", "succeeded", "failed", "cancelled", "interrupted" ] } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "Cursor: the last id of the previous page (next_starting_after)." }, { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Only objects created with this external_id." }, { "name": "metadata", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object" }, "description": "metadata[key]=value: only objects whose metadata has that value (up to 5 keys; metadata.key=value also works)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Video" } } } } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}": { "get": { "summary": "Get a video", "tags": [ "Videos" ], "x-vuesy-scope": "videos:read", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Video" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/jobs/{id}/cancel": { "post": { "summary": "Cancel a video or export (credits come back)", "tags": [ "Videos" ], "x-vuesy-scope": "videos:write", "x-vuesy-credits": "free", "description": "Works on a queued or running video or export; a finished one comes back unchanged.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Video" }, { "$ref": "#/components/schemas/Export" } ] } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/videos/{id}/export": { "post": { "summary": "Export the video to MP4 (1080p)", "tags": [ "Exports" ], "x-vuesy-scope": "videos:write", "x-vuesy-credits": "first export free, then 4", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" }, "description": "Any unique string per new request. Retrying with the same key and body returns the same object (never charges twice)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quality": { "enum": [ "high", "medium", "fast" ], "description": "Accepted; every export is rendered at 1080p.", "default": "medium" }, "download_filename": { "type": "string", "description": "File name of the download (your brand, not Vuesy's); .mp4 is added. Default vuesy_video.mp4.", "maxLength": 200 }, "external_id": { "type": "string", "description": "Default: the video's." }, "metadata": { "type": "object", "description": "Default: the video's metadata." } } } } } }, "responses": { "200": { "description": "Replay of the same Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/exports": { "get": { "summary": "List exports (newest first)", "tags": [ "Exports" ], "x-vuesy-scope": "videos:read", "x-vuesy-credits": "free", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "Cursor: the last id of the previous page (next_starting_after)." }, { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Only objects created with this external_id." }, { "name": "metadata", "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object" }, "description": "metadata[key]=value: only objects whose metadata has that value (up to 5 keys; metadata.key=value also works)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/List" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Export" } } } } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/exports/{id}": { "get": { "summary": "Get an export (download_url when succeeded)", "tags": [ "Exports" ], "x-vuesy-scope": "videos:read", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads/script": { "post": { "summary": "Upload a long script", "tags": [ "Uploads" ], "x-vuesy-scope": "videos:write", "x-vuesy-credits": "free", "description": "Pass key as script_key to POST /v1/videos.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 50000 } }, "required": [ "text" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScriptUpload" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/uploads": { "post": { "summary": "Get a signed URL to upload your own voiceover or music", "tags": [ "Uploads" ], "x-vuesy-scope": "videos:write", "x-vuesy-credits": "free", "description": "Then PUT the file bytes to put_url (any common audio format) within 1 hour, and pass key as audio_key or music_key to POST /v1/videos.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "enum": [ "audio", "music" ] } }, "required": [ "kind" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upload" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/languages": { "get": { "summary": "Voice languages", "tags": [ "Voices" ], "x-vuesy-scope": "any", "x-vuesy-credits": "free", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Languages" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/voices": { "get": { "summary": "Voices of a language", "tags": [ "Voices" ], "x-vuesy-scope": "any", "x-vuesy-credits": "free", "parameters": [ { "name": "lang", "in": "query", "schema": { "type": "string" }, "description": "Language code (default en)." }, { "name": "quality", "in": "query", "schema": { "enum": [ "standard", "high" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Voices" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/music": { "get": { "summary": "Background music catalog by mood", "tags": [ "Voices" ], "x-vuesy-scope": "any", "x-vuesy-credits": "free", "description": "For music_style ('') or music_track ('/') on POST /v1/videos.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Music" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/references": { "get": { "summary": "Videos of a YouTube channel (references for scripts and thumbnails)", "tags": [ "Scripts & thumbnails" ], "x-vuesy-scope": "scripts:write or thumbnails:write", "x-vuesy-credits": "free", "parameters": [ { "name": "channel_url", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "schema": { "enum": [ "recent", "popular" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/References" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/scripts": { "post": { "summary": "Write a script with AI (async)", "tags": [ "Scripts & thumbnails" ], "x-vuesy-scope": "scripts:write", "x-vuesy-credits": "4 (or included in plan)", "description": "Give channel_url, video_ids or only topic (then Vuesy finds 3 references on YouTube; if it finds none, the task fails with nothing charged).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" }, "description": "Any unique string per new request. Retrying with the same key and body returns the same object (never charges twice)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_url": { "type": "string", "description": "YouTube channel link; the first 3 videos are the references. Or pass video_ids.", "maxLength": 500 }, "video_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 3 }, "reference_titles": { "type": "array", "items": { "type": "string" }, "maxItems": 3 }, "topic": { "type": "string", "description": "What the script is about. Alone (no channel_url / video_ids) Vuesy searches YouTube for the topic and uses 3 videos as style references (same price).", "maxLength": 400, "minLength": 8 }, "minutes": { "type": "integer", "minimum": 1, "maximum": 90, "default": 8 }, "lang": { "type": "string", "description": "Force the script language (e.g. en, es)." }, "sort": { "enum": [ "recent", "popular" ], "default": "recent" }, "external_id": { "type": "string", "description": "Your own order or customer id: 1-128 printable ASCII characters, no spaces. Filter lists with ?external_id=." }, "metadata": { "type": "object", "description": "Your own data, echoed on the object and on webhooks: up to 20 keys [A-Za-z0-9_.-]{1,40}, string values up to 500 characters (numbers become strings), 8 KB in total." } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/scripts/{id}": { "get": { "summary": "Get a script task", "tags": [ "Scripts & thumbnails" ], "x-vuesy-scope": "scripts:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/thumbnails": { "post": { "summary": "Make a thumbnail with AI (async)", "tags": [ "Scripts & thumbnails" ], "x-vuesy-scope": "thumbnails:write", "x-vuesy-credits": "4 (or included in plan)", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,64}$" }, "description": "Any unique string per new request. Retrying with the same key and body returns the same object (never charges twice)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 300 }, "text": { "type": "string", "maxLength": 120 }, "subject": { "type": "string", "maxLength": 300 }, "script": { "type": "string", "maxLength": 50000 }, "with_text": { "type": "boolean", "default": true }, "channel_url": { "type": "string", "description": "YouTube channel link; the first 3 videos are the references. Or pass video_ids.", "maxLength": 500 }, "video_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 3 }, "sort": { "enum": [ "recent", "popular" ], "default": "recent" }, "external_id": { "type": "string", "description": "Your own order or customer id: 1-128 printable ASCII characters, no spaces. Filter lists with ?external_id=." }, "metadata": { "type": "object", "description": "Your own data, echoed on the object and on webhooks: up to 20 keys [A-Za-z0-9_.-]{1,40}, string values up to 500 characters (numbers become strings), 8 KB in total." } }, "required": [ "title" ] } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/thumbnails/{id}": { "get": { "summary": "Get a thumbnail task", "tags": [ "Scripts & thumbnails" ], "x-vuesy-scope": "thumbnails:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "post": { "summary": "Add a webhook endpoint (max 3 per key)", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "description": "Events for videos, exports, scripts and thumbnails created by THIS key, sent when they end. The secret is shown only here and on rotate-secret.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "https, port 443, a public host name (no IP, no localhost/.local/.internal); every address it resolves to must be public. 10 s timeout, no redirects.", "maxLength": 2000 }, "events": { "type": "array", "items": { "type": "string" }, "description": "Default (or [\"*\"]): all events." }, "description": { "type": "string", "maxLength": 200 } }, "required": [ "url" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "List this key's webhooks", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "get": { "summary": "Get a webhook", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Update a webhook (url, events, description, enabled)", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "https, port 443, a public host name (no IP, no localhost/.local/.internal); every address it resolves to must be public. 10 s timeout, no redirects.", "maxLength": 2000 }, "events": { "type": "array", "items": { "type": "string" }, "description": "Default (or [\"*\"]): all events." }, "description": { "type": "string", "maxLength": 200 }, "enabled": { "type": "boolean", "description": "true re-enables an endpoint disabled after failures." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a webhook", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" }, "object": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "summary": "Send one signed webhook.test event now", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_test" }, "event_id": { "type": "string" }, "delivered": { "type": "boolean" }, "status_code": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "summary": "New signing secret (the old one stops at once)", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "summary": "Recent deliveries (newest first, kept 7 days)", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{evt}/retry": { "post": { "summary": "Send an event again (same event id)", "tags": [ "Webhooks" ], "x-vuesy-scope": "videos:read or videos:write", "x-vuesy-credits": "free", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "evt", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "webhook_delivery" }, "status": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account": { "get": { "summary": "Your plan, API limits and this key's usage today", "tags": [ "Account" ], "x-vuesy-scope": "any", "x-vuesy-credits": "free", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/credits": { "get": { "summary": "Credit balance", "tags": [ "Account" ], "x-vuesy-scope": "credits:read", "x-vuesy-credits": "free", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/credits/history": { "get": { "summary": "Credit movements (newest first)", "tags": [ "Account" ], "x-vuesy-scope": "credits:read", "x-vuesy-credits": "free", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsHistory" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/quote": { "get": { "summary": "Price of a video in credits", "tags": [ "Account" ], "x-vuesy-scope": "any", "x-vuesy-credits": "free", "parameters": [ { "name": "chars", "in": "query", "schema": { "type": "integer" }, "description": "Script length in characters (or pass duration_sec)." }, { "name": "duration_sec", "in": "query", "schema": { "type": "integer" }, "description": "Length in seconds (for your own audio)." }, { "name": "lang", "in": "query", "schema": { "type": "string" } }, { "name": "voice", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "event": { "post": { "summary": "An event (video.*, export.*, script.*, thumbnail.*, webhook.test)", "parameters": [ { "name": "Vuesy-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=.\")>. Compare in constant time; reject t older than 5 minutes." }, { "name": "Vuesy-Event-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^evt_[a-f0-9]{20}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "2XX": { "description": "Received. Any other answer (or none in 10 s) is retried at +30 s, 2 min, 10 min, 30 min, 2 h, 6 h and 12 h." } } } } } }