{ "openapi": "3.1.0", "info": { "title": "Voice1 API", "version": "1.0.0", "contact": { "url": "https://voice1.pro/docs" }, "description": "The Voice1 REST API: generate speech from text, track progress and download output files. Full documentation: https://voice1.pro/docs" }, "servers": [ { "url": "https://voice1.pro/api" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication", "x-displayName": "Authentication" }, { "name": "Voices", "x-displayName": "Voices" }, { "name": "TextToSpeech", "x-displayName": "Text to speech" }, { "name": "History", "x-displayName": "History" }, { "name": "Files", "x-displayName": "Output files" }, { "name": "Account", "x-displayName": "Account" }, { "name": "Dialogue", "x-displayName": "Dialogue" } ], "paths": { "/v1/auth/me": { "get": { "operationId": "authMe", "tags": [ "Authentication" ], "summary": "Get account", "description": "Returns the profile and current credit balance of the API key's owner. Call this endpoint to check that your key works.", "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "credits": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } }, "example": { "id": "u_3b91d2c07a5e4f18b6d9a0c2", "name": "Nguyễn Minh Anh", "email": "minhanh@example.com", "credits": 128450, "createdAt": "2026-03-14T08:00:00.000Z" } } } }, "401": { "description": "`unauthorized` — The API key is missing, invalid or revoked, or the account is locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/voices": { "get": { "operationId": "voicesList", "tags": [ "Voices" ], "summary": "List voices", "description": "Browse the voice library by language, gender, age and other filters. This is your first step: get a voiceId to generate speech with.\n\nPublic endpoint, no API key required. The voice list changes rarely — you may cache it for a few minutes.\n\nFilter parameters with invalid values are ignored (treated as no filter) instead of returning an error — double-check spelling if the results aren't what you expect.\n\nA voice's `id` is an alphanumeric string (up to 64 characters) — pass it unchanged as `voiceId` when creating a task. `previewUrl` is a public preview link and may change — don't store it long-term.", "security": [], "parameters": [ { "name": "provider", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "elevenlabs" ] }, "description": "Required. Any other engine returns 404.", "example": "elevenlabs" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ISO language code, e.g. vi, en.", "example": "vi" }, { "name": "gender", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "male", "female", "neutral" ] }, "description": "Voice gender." }, { "name": "age", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "young", "middle_aged", "old" ] }, "description": "Age group." }, { "name": "accent", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Regional accent, e.g. northern, southern." }, { "name": "useCase", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "conversational", "narrative_story", "characters_animation", "social_media", "entertainment_tv", "advertisement", "informative_educational" ] }, "description": "Intended use case." }, { "name": "quality", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "standard", "high" ] }, "description": "Voice quality tier." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "trending", "latest", "most_used" ] }, "description": "Sort order. Defaults to trending." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page to return, from 1 to 500. Out-of-range values fall back to page 1.", "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Voices per page, from 1 to 100. Defaults to 24; out-of-range values also fall back to 24.", "example": 24 }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by name or description (up to 100 characters)." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "previewUrl": { "type": "string" }, "gender": { "type": "string" }, "age": { "type": "string" }, "language": { "type": "string" }, "accent": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "accent": { "type": "string" }, "previewUrl": { "type": "string" } } } }, "useCase": { "type": "string" }, "category": { "type": "string" }, "quality": { "type": "string" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "example": { "items": [ { "id": "jdlxsPOZOHdGEfcItXVu", "provider": "elevenlabs", "name": "Hiền", "description": "Giọng nữ miền Bắc, ấm áp, hợp kể chuyện.", "previewUrl": "https://cdn.example.com/previews/hien.mp3", "gender": "female", "age": "young", "language": "vi", "accent": "northern", "tags": [ "warm", "narrative_story" ], "languages": [ { "language": "vi", "accent": "northern", "previewUrl": "https://cdn.example.com/previews/hien.mp3" } ], "useCase": "narrative_story", "category": "narrative_story", "quality": "high" } ], "total": 1, "page": 1, "pageSize": 24, "hasMore": false } } } }, "400": { "description": "`bad_request` — Rare: invalid filter values (gender, sort…) are usually ignored rather than rejected.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`unsupported_provider` — Unsupported engine. Only provider=elevenlabs is currently accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — Too many requests. Wait the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`voices_unavailable` — The voice library is temporarily unavailable. Please try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/voices/trending": { "get": { "operationId": "voicesTrending", "tags": [ "Voices" ], "summary": "Most-used voices", "description": "A short list of popular voices — a good set of default suggestions for new users.\n\nThe list is already sorted by popularity: the first item is the most popular voice.", "security": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "previewUrl": { "type": "string" }, "gender": { "type": "string" }, "age": { "type": "string" }, "language": { "type": "string" }, "accent": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "accent": { "type": "string" }, "previewUrl": { "type": "string" } } } }, "useCase": { "type": "string" }, "category": { "type": "string" }, "quality": { "type": "string" } } } }, "example": [ { "id": "jdlxsPOZOHdGEfcItXVu", "provider": "elevenlabs", "name": "Hiền", "description": "Giọng nữ miền Bắc, ấm áp, hợp kể chuyện.", "previewUrl": "https://cdn.example.com/previews/hien.mp3", "gender": "female", "age": "young", "language": "vi", "accent": "northern", "tags": [ "warm", "narrative_story" ], "languages": [ { "language": "vi", "accent": "northern", "previewUrl": "https://cdn.example.com/previews/hien.mp3" } ], "useCase": "narrative_story", "category": "narrative_story", "quality": "high" } ] } } } } } }, "/v1/text-to-speech/{provider}": { "post": { "operationId": "ttsCreate", "tags": [ "TextToSpeech" ], "summary": "Create speech", "description": "Creates a text-to-speech task. Tasks run asynchronously — use the History endpoints to track status and fetch the files.\n\nReturns 201 when a new task is created. Credits are charged immediately and refunded automatically if the task fails.\n\nSend an `Idempotency-Key` header to avoid duplicates on unreliable networks: resending with the same key returns the original task (200 + `Idempotent-Replay: true` header) without charging credits a second time. The same key with a different text / voice / model → 409 `idempotency_key_reused`.", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "elevenlabs" ] }, "description": "Engine used to generate speech.", "example": "elevenlabs" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" }, "description": "Resending the same key returns the task already created, without charging again." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A friendly name for the recording (up to 120 characters). If omitted, the first 48 characters of the text are used." }, "text": { "type": "string", "description": "The text to speak. Up to 250,000 characters of spoken text and 600,000 characters of raw input." }, "voiceId": { "type": "string", "description": "Voice ID from GET /v1/voices (an alphanumeric string — use it unchanged). A malformed ID → 400 bad_request, with no credits charged." }, "voiceName": { "type": "string", "description": "Voice name shown in history (up to 120 characters). Optional: if omitted, it is filled in from `voiceId` when possible." }, "modelId": { "type": "string", "description": "Model ID, e.g. eleven_v4. The model must belong to the engine in the path." }, "settings": { "type": "object", "properties": { "speed": { "type": "integer" }, "stability": { "type": "number" }, "similarity": { "type": "number" }, "style": { "type": "integer" }, "speakerBoost": { "type": "boolean" }, "language": { "type": "string" }, "leveling": { "type": "integer" } }, "description": "Voice settings: speed, stability, similarity, style, language, leveling. Up to 4,096 bytes of JSON. If omitted, defaults apply." }, "exportTranscript": { "type": "boolean", "description": "Also export SRT subtitles (5% surcharge). Defaults to false." }, "inputFormat": { "type": "string", "enum": [ "text" ], "description": "Defaults to 'text'. SRT input ('srt') is temporarily disabled — sending 'srt' returns 503 feature_disabled." } }, "required": [ "text", "voiceId", "modelId" ] }, "example": { "name": "Lời chào buổi sáng", "text": "Xin chào, chúc bạn một ngày làm việc hiệu quả!", "voiceId": "jdlxsPOZOHdGEfcItXVu", "voiceName": "Hiền", "modelId": "eleven_v4", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "exportTranscript": true } } } }, "responses": { "200": { "description": "Replay: the task created earlier with the same Idempotency-Key (batch: every file matched a requestKey, created = 0). No extra credits charged.", "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "voiceId": { "type": "string" }, "voiceName": { "type": "string" }, "modelId": { "type": "string" }, "language": { "type": "string" }, "settings": { "type": "object", "properties": { "speed": { "type": "integer" }, "stability": { "type": "number" }, "similarity": { "type": "number" }, "style": { "type": "integer" }, "speakerBoost": { "type": "boolean" }, "language": { "type": "string" }, "leveling": { "type": "integer" } } }, "creditsCost": { "type": "integer" }, "exportTranscript": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "example": { "id": "tsk_24598d03cfcac9a82eec36f0", "kind": "tts", "provider": "elevenlabs", "name": "Lời chào buổi sáng", "text": "Xin chào, chúc bạn một ngày làm việc hiệu quả!", "status": "queued", "progress": 0, "voiceId": "jdlxsPOZOHdGEfcItXVu", "voiceName": "Hiền", "modelId": "eleven_v4", "language": "vi", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "creditsCost": 500, "exportTranscript": true, "createdAt": "2026-10-02T08:00:00.000Z" } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "voiceId": { "type": "string" }, "voiceName": { "type": "string" }, "modelId": { "type": "string" }, "language": { "type": "string" }, "settings": { "type": "object", "properties": { "speed": { "type": "integer" }, "stability": { "type": "number" }, "similarity": { "type": "number" }, "style": { "type": "integer" }, "speakerBoost": { "type": "boolean" }, "language": { "type": "string" }, "leveling": { "type": "integer" } } }, "creditsCost": { "type": "integer" }, "exportTranscript": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "example": { "id": "tsk_24598d03cfcac9a82eec36f0", "kind": "tts", "provider": "elevenlabs", "name": "Lời chào buổi sáng", "text": "Xin chào, chúc bạn một ngày làm việc hiệu quả!", "status": "queued", "progress": 0, "voiceId": "jdlxsPOZOHdGEfcItXVu", "voiceName": "Hiền", "modelId": "eleven_v4", "language": "vi", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "creditsCost": 500, "exportTranscript": true, "createdAt": "2026-10-02T08:00:00.000Z" } } } }, "400": { "description": "`bad_request` — A required field is missing, a value has the wrong type, or a limit was exceeded (including text that is too long). `message` explains what is wrong.\n\n`invalid_provider` — The engine in the path is not supported.\n\n`invalid_model` — `modelId` does not exist or does not belong to the selected engine.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized` — The API key is missing, invalid or revoked, or the account is locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`insufficient_credits` — Not enough credits. No task is created and no credits are charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`forbidden_origin` — Only seen when calling from a browser: a write request (POST, DELETE) that did not come from our website. Call from your server.\n\n`content_hold` — Task creation via the API is paused because many recent requests were rejected for their text content (`content_blocked` errors). No credits are charged — review your text and retry after the `Retry-After` seconds (15 minutes, longer if it repeats).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_key_reused` — This Idempotency-Key was already used for a different request (different text, voice or model). Nothing is created and no credits are charged — use a new key for each new request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`payload_too_large` — The body exceeds 10 MB. Text over the character limit returns 400 bad_request, not 413.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type` — `Content-Type: application/json` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — More than about 600 tasks created per minute (test keys `vs_test_`: 30). Wait the number of seconds in the `Retry-After` header, then resend.\n\n`queue_full` — 1,000 tasks created with API keys are already waiting (for batch creation: waiting tasks + files in the batch exceed this). Nothing is created and no credits are charged — wait for some to finish, then resend after the `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`tasks_disabled` — Speech generation is temporarily paused for maintenance. No credits are charged — try again later.\n\n`system_busy` — The system is overloaded and is temporarily not accepting new tasks via the API. No credits are charged — retry after the `Retry-After` seconds, with increasing delays.\n\n`feature_disabled` — SRT input (inputFormat: 'srt') is temporarily disabled. No credits are charged — send plain text instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/text-to-speech/{provider}/batch": { "post": { "operationId": "ttsBatch", "tags": [ "TextToSpeech" ], "summary": "Create speech in batch", "description": "Create up to 25 recordings in a single request. Each file has its own voice, model and settings.\n\nAll or nothing: if credits run short or you would exceed the queued-task limit, no files are created and nothing is charged.\n\n`created` is the number of tasks actually created. If you resend the whole batch with the same `requestKey`s, files that already exist are returned (and not charged again); if no new file is created, the response is 200 with `created: 0`.\n\nRate limits count each request once, regardless of the number of files.", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "elevenlabs" ] }, "description": "Engine used to generate speech.", "example": "elevenlabs" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "requestKey": { "type": "string", "description": "Per-file idempotency key (optional, same format as `Idempotency-Key`)." }, "inputFormat": { "type": "string", "enum": [ "text" ], "description": "Defaults to 'text'. SRT input ('srt') is temporarily disabled — sending 'srt' returns 503 feature_disabled." }, "name": { "type": "string" }, "text": { "type": "string" }, "voiceId": { "type": "string" }, "modelId": { "type": "string" }, "settings": { "type": "object", "properties": { "speed": { "type": "integer" }, "stability": { "type": "number" }, "similarity": { "type": "number" }, "style": { "type": "integer" }, "speakerBoost": { "type": "boolean" }, "language": { "type": "string" }, "leveling": { "type": "integer" } } }, "exportTranscript": { "type": "boolean" } } }, "description": "The files to create, from 1 to 25. Each item has the same shape as the Create speech request body." } }, "required": [ "items" ] }, "example": { "items": [ { "name": "Chương 1", "text": "Chương một: khởi đầu.", "voiceId": "jdlxsPOZOHdGEfcItXVu", "modelId": "eleven_v4", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "exportTranscript": false, "requestKey": "book-42-ch-01" }, { "name": "Chương 2", "text": "Chương hai: tiếp nối.", "voiceId": "ZsjEJaLQy3sgvwxicmDx", "modelId": "eleven_v4", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "exportTranscript": false, "requestKey": "book-42-ch-02" } ] } } } }, "responses": { "200": { "description": "Replay: the task created earlier with the same Idempotency-Key (batch: every file matched a requestKey, created = 0). No extra credits charged.", "headers": { "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "voiceId": { "type": "string" }, "voiceName": { "type": "string" }, "modelId": { "type": "string" }, "language": { "type": "string" }, "settings": { "type": "object", "properties": { "speed": { "type": "integer" }, "stability": { "type": "number" }, "similarity": { "type": "number" }, "style": { "type": "integer" }, "speakerBoost": { "type": "boolean" }, "language": { "type": "string" }, "leveling": { "type": "integer" } } }, "creditsCost": { "type": "integer" }, "exportTranscript": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "created": { "type": "integer" } } }, "example": { "tasks": [ { "id": "tsk_5e0c2a7b9d1f3e4a6b8c0d2e", "kind": "tts", "provider": "elevenlabs", "name": "Chương 1", "text": "Chương một: khởi đầu.", "status": "queued", "progress": 0, "voiceId": "jdlxsPOZOHdGEfcItXVu", "voiceName": "", "modelId": "eleven_v4", "language": "vi", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "creditsCost": 500, "exportTranscript": false, "createdAt": "2026-10-02T08:00:00.000Z" }, { "id": "tsk_8a3f1c6e2b9d4f7a0c5e1b3d", "kind": "tts", "provider": "elevenlabs", "name": "Chương 2", "text": "Chương hai: tiếp nối.", "status": "queued", "progress": 0, "voiceId": "ZsjEJaLQy3sgvwxicmDx", "voiceName": "", "modelId": "eleven_v4", "language": "vi", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "creditsCost": 500, "exportTranscript": false, "createdAt": "2026-10-02T08:00:00.000Z" } ], "created": 2 } } } }, "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "voiceId": { "type": "string" }, "voiceName": { "type": "string" }, "modelId": { "type": "string" }, "language": { "type": "string" }, "settings": { "type": "object", "properties": { "speed": { "type": "integer" }, "stability": { "type": "number" }, "similarity": { "type": "number" }, "style": { "type": "integer" }, "speakerBoost": { "type": "boolean" }, "language": { "type": "string" }, "leveling": { "type": "integer" } } }, "creditsCost": { "type": "integer" }, "exportTranscript": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "created": { "type": "integer" } } }, "example": { "tasks": [ { "id": "tsk_5e0c2a7b9d1f3e4a6b8c0d2e", "kind": "tts", "provider": "elevenlabs", "name": "Chương 1", "text": "Chương một: khởi đầu.", "status": "queued", "progress": 0, "voiceId": "jdlxsPOZOHdGEfcItXVu", "voiceName": "", "modelId": "eleven_v4", "language": "vi", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "creditsCost": 500, "exportTranscript": false, "createdAt": "2026-10-02T08:00:00.000Z" }, { "id": "tsk_8a3f1c6e2b9d4f7a0c5e1b3d", "kind": "tts", "provider": "elevenlabs", "name": "Chương 2", "text": "Chương hai: tiếp nối.", "status": "queued", "progress": 0, "voiceId": "ZsjEJaLQy3sgvwxicmDx", "voiceName": "", "modelId": "eleven_v4", "language": "vi", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "creditsCost": 500, "exportTranscript": false, "createdAt": "2026-10-02T08:00:00.000Z" } ], "created": 2 } } } }, "400": { "description": "`bad_request` — If any file has invalid data (including its model or settings), the error names its position, e.g. \"File 2 (Chương 2): …\". No files are created.\n\n`invalid_provider` — The engine in the path is not supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`unauthorized` — The API key is missing, invalid or revoked, or the account is locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "`insufficient_credits` — Not enough credits. No task is created and no credits are charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`forbidden_origin` — Only seen when calling from a browser: a write request (POST, DELETE) that did not come from our website. Call from your server.\n\n`content_hold` — Task creation via the API is paused because many recent requests were rejected for their text content (`content_blocked` errors). No credits are charged — review your text and retry after the `Retry-After` seconds (15 minutes, longer if it repeats).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`idempotency_key_reused` — This Idempotency-Key was already used for a different request (different text, voice or model). Nothing is created and no credits are charged — use a new key for each new request.\n\n`task_conflict` — Rare: the task changed state because of another request running concurrently. No credits are charged — reload and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`payload_too_large` — The body exceeds 10 MB. Text over the character limit returns 400 bad_request, not 413.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type` — `Content-Type: application/json` is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` — More than about 600 tasks created per minute (test keys `vs_test_`: 30). Wait the number of seconds in the `Retry-After` header, then resend.\n\n`queue_full` — 1,000 tasks created with API keys are already waiting (for batch creation: waiting tasks + files in the batch exceed this). Nothing is created and no credits are charged — wait for some to finish, then resend after the `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`tasks_disabled` — Speech generation is temporarily paused for maintenance. No credits are charged — try again later.\n\n`system_busy` — The system is overloaded and is temporarily not accepting new tasks via the API. No credits are charged — retry after the `Retry-After` seconds, with increasing delays.\n\n`feature_disabled` — SRT input (inputFormat: 'srt') is temporarily disabled. No credits are charged — send plain text instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/history": { "get": { "operationId": "historyList", "tags": [ "History" ], "summary": "List tasks", "description": "Lists the tasks you have created, newest first, with optional filters by kind and status. Long text may be truncated to 2,000 characters (textTruncated: true); fetch the full text with Get task.\n\nThere is no search-by-name parameter. Tasks you delete while they are running are removed entirely, so they no longer appear in the list.\n\n`total` is counted up to 1,000 tasks (or up to the end of the requested page if that is further). Beyond that, `total` is a lower bound and the response also has `totalCapped: true` — use `hasMore` to know whether another page exists.", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tts", "srt", "dialogue", "voice_changer", "dubbing" ] }, "description": "Filter by task kind. Invalid values are ignored (no filtering).", "example": "tts" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "queued", "processing", "completed", "failed" ] }, "description": "Filter by status. Lifecycle: 'queued' (received, not started yet) → 'processing' → 'completed' | 'failed'. Invalid values are ignored." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page to return, starting at 1.", "example": 1 }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tasks per page, from 1 to 100. Defaults to 10. Out-of-range values are clamped to 1 or 100.", "example": 10 } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "provider": { "type": "string" }, "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "progress": { "type": "integer" }, "voiceId": { "type": "string" }, "voiceName": { "type": "string" }, "modelId": { "type": "string" }, "language": { "type": "string" }, "settings": { "type": "object", "properties": { "speed": { "type": "integer" }, "stability": { "type": "number" }, "similarity": { "type": "number" }, "style": { "type": "integer" }, "speakerBoost": { "type": "boolean" }, "language": { "type": "string" }, "leveling": { "type": "integer" } } }, "creditsCost": { "type": "integer" }, "exportTranscript": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "output": { "type": "object", "properties": { "audioUrl": { "type": "string" }, "srtUrl": { "type": "string" }, "wordsUrl": { "type": "string" }, "durationSec": { "type": "number" }, "downloadUrl": { "type": "string" }, "downloadUrlExpiresAt": { "type": "string", "format": "date-time" } } }, "completedAt": { "type": "string", "format": "date-time" }, "filesExpireAt": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "example": { "items": [ { "id": "tsk_24598d03cfcac9a82eec36f0", "kind": "tts", "provider": "elevenlabs", "name": "Lời chào buổi sáng", "text": "Xin chào, chúc bạn một ngày làm việc hiệu quả!", "status": "completed", "progress": 100, "voiceId": "jdlxsPOZOHdGEfcItXVu", "voiceName": "Hiền", "modelId": "eleven_v4", "language": "vi", "settings": { "speed": 1, "stability": 0.5, "similarity": 0.75, "style": 0, "speakerBoost": true, "language": "vi", "leveling": 0 }, "creditsCost": 500, "exportTranscript": true, "createdAt": "2026-10-02T08:00:00.000Z", "output": { "audioUrl": "/api/v1/audio/tsk_24598d03cfcac9a82eec36f0/audio.mp3", "srtUrl": "/api/v1/audio/tsk_24598d03cfcac9a82eec36f0/transcript.srt", "wordsUrl": "/api/v1/audio/tsk_24598d03cfcac9a82eec36f0/transcript.json", "durationSec": 3.8, "downloadUrl": "https://voice1.pro/api/v1/download/tsk_24598d03cfcac9a82eec36f0/audio.mp3?e=1791536400&s=8c1f0e5a2b7d4c9e3f6a1b8d0c5e2f7a9b4d6c1e3f8a0b5d2c7e9f1a4b6d8c0e", "downloadUrlExpiresAt": "2026-10-09T09:00:00.000Z" }, "completedAt": "2026-10-02T08:01:00.000Z", "filesExpireAt": "2026-10-09T08:01:00.000Z" } ], "total": 1, "page": 1, "pageSize": 10, "hasMore": false } } } }, "401": { "description": "`unauthorized` — The API key is missing, invalid or revoked, or the account is locked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/history/{id}": { "get": { "operationId": "historyGet", "tags": [ "History" ], "summary": "Get task", "description": "Returns the status, progress and file paths of a single task. To track progress, use Get task statuses instead of polling this endpoint.\n\nQueued or running tasks include `etaDoneMinSec` and `etaDoneMaxSec` — an estimated time range until completion, meant only for display and for spacing out polling. The failure reason is in `error`.\n\n`output.downloadUrl`: a full audio download link that opens directly with no Authorization header (for Make, Zapier, n8n, an