{ "openapi": "3.1.0", "info": { "title": "Breeze Developer API", "description": "Breeze Developer API for models, voices, text-to-speech, history, balance, usage, and browser-managed API keys.", "version": "1.0.0" }, "paths": { "/v1/models": { "get": { "tags": [ "Models" ], "summary": "List models", "description": "List TTS models available to the authenticated account. Each model includes a human-readable description and the ISO 639-1 language codes accepted by that model.", "operationId": "models_list", "responses": { "200": { "description": "Supported TTS models.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelResponse" } } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nMatch a model to the spoken language.\nFind a voice for the selected language.\nGenerate speech with your model and voice.\n\n\n
" }, "x-breeze-api-name": "List models", "x-breeze-docs-group": "Models", "x-breeze-docs-href": "/docs/api-reference/models/list", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/models\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nfor model in client.models.list():\n print(model[\"model_id\"], model[\"name\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst models = await client.models.list();\nfor (const model of models) {\n console.log(model.modelId, model.name);\n}" } ] } }, "/v1/text-to-speech/{voice_id}": { "post": { "tags": [ "Text to Speech" ], "summary": "Convert text to speech", "description": "Synthesize text to audio using the given voice. For complete JSON audio and timing, use [Convert with timestamps](https://docs.breezeblue.ai/api-reference/text-to-speech/convert-with-timestamps). See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing) for SDK and CLI examples.", "operationId": "tts_generate", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice ID to use for speech generation. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, { "name": "output_format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Format", "default": "mp3" }, "description": "Audio encoding: mp3, wav, flac, pcm, aac, or opus. Optionally add sample rate (Hz) and bitrate (kbps), e.g. mp3_44100_128 or wav_48000. Default: mp3. See [Output formats](https://docs.breezeblue.ai/concepts/output-format)." }, { "name": "delivery", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(sync|async)$", "default": "sync", "title": "Delivery" }, "description": "Response mode: sync returns audio; async returns a background job to poll. Default: sync. See [Async jobs](https://docs.breezeblue.ai/guides/text-to-speech#async-jobs)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsRequest" } } } }, "responses": { "200": { "description": "Binary audio stream. Content-Type matches the requested output_format.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "history-item-id": { "description": "History item ID for the generated audio.", "schema": { "type": "string" } }, "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "202": { "description": "Accepted background TTS job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncTtsJobResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose intent, emotion, and delivery.\nGet complete audio with word timing.\nReceive audio as it is generated.\nFollow HTTP, SDK, and async examples.\n\n\n
" }, "x-breeze-api-name": "Convert text to speech", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/convert", "x-breeze-errors": [ { "code": "VALIDATION_ERROR", "description": "The request body failed schema validation." }, { "code": "BAD_REQUEST", "description": "The request body or query parameter is not valid for this endpoint." }, { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." }, { "code": "GENERATION_CAPACITY_EXCEEDED", "description": "Generation capacity is temporarily exhausted." }, { "code": "UPSTREAM_GENERATION_ERROR", "description": "The downstream generation service failed." }, { "code": "UPSTREAM_TIMEOUT", "description": "The downstream generation service timed out." } ], "x-breeze-notes": [ "Use voice_settings.guidance_scale to adjust how strongly generation follows the prompt and reference voice. Accepted range: 1.0 to 10.0.", "Breeze generates native 24000 Hz audio. A profile that names a different sample rate resamples that output for downstream format compatibility; it does not add source bandwidth." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"text\": \"I can’t believe you brought him here!\",\n \"model_id\": \"breeze-tts-2\",\n \"instructions\": \"Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.\",\n \"voice_settings\": {\n \"guidance_scale\": 4.0\n }\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "from pathlib import Path\n\nfrom breeze_blue import save\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\naudio = client.text_to_speech.convert(\n voice_id=\"voc_xeh3w54cqvnp\",\n text=\"I can’t believe you brought him here!\",\n instructions=\"Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.\",\n model_id=\"breeze-tts-2\",\n voice_settings={\"guidance_scale\": 4.0},\n)\nsave(audio, Path(\"out.mp3\"))" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { save } from \"@breeze.blue/sdk/node\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst audio = await client.textToSpeech.convert(\n \"voc_xeh3w54cqvnp\",\n {\n text: \"I can’t believe you brought him here!\",\n instructions: \"Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.\",\n modelId: \"breeze-tts-2\",\n voiceSettings: { guidanceScale: 4.0 },\n },\n);\nawait save(audio, \"out.mp3\");" } ] } }, "/v1/text-to-speech/{voice_id}/with-timestamps": { "post": { "tags": [ "Text to Speech" ], "summary": "Convert with timestamps", "description": "Generate speech with word timestamps. Returns one complete JSON response, or a background job with delivery=async.", "operationId": "tts_generate_with_timestamps", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice ID to use for speech generation. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, { "name": "output_format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Format", "default": "mp3" }, "description": "Audio encoding: mp3, wav, flac, pcm, aac, or opus. Optional sample rate and bitrate profiles follow ordinary synchronous TTS, e.g. wav_48000. Default: mp3. See [Output formats](https://docs.breezeblue.ai/concepts/output-format)." }, { "name": "delivery", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(sync|async)$", "default": "sync", "title": "Delivery" }, "description": "sync (default) returns audio_base64 and word_timestamps. async returns a job ID immediately; poll Get generation job for the result. See [Async jobs](https://docs.breezeblue.ai/guides/text-to-speech#async-jobs)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsConvertWithTimestampsRequest" } } } }, "responses": { "200": { "description": "Complete audio and word timestamps. The history-item-id header identifies the saved audio.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpeechWithTimestampsResponse" } } }, "headers": { "history-item-id": { "description": "History item ID for the generated audio.", "schema": { "type": "string" } }, "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "202": { "description": "Accepted background TTS job. Poll Get generation job for word_timestamps and the audio download URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncTtsJobResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "HTTP 502 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose intent, emotion, and delivery.\nBuild captions with word timing.\nGenerate audio without word timing.\nStream audio with word timing.\n\n\n
" }, "x-breeze-api-name": "Convert with timestamps", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/convert-with-timestamps", "x-breeze-errors": [ { "code": "GENERATION_INVALID_RESPONSE", "description": "The generation service returned missing or invalid word timestamps." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." } ], "x-breeze-notes": [ "Supports BreezeBlue TTS 2 models and ordinary TTS output formats. Timestamps follow the delivered audio, including speed and segment pauses. CJK tokens may contain multiple characters; character alignment is not provided. timestamp_mode applies only to streaming.", "See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing) for SDK and CLI examples, [Convert text to speech](https://docs.breezeblue.ai/api-reference/text-to-speech/convert-text-to-speech) for binary audio, and [Stream speech with word timestamps](https://docs.breezeblue.ai/api-reference/text-to-speech/stream-speech-with-word-timestamps) for incremental audio and timing." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp/with-timestamps\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"text\": \"Hello world.\",\n \"model_id\": \"breeze-tts-2-multilingual\",\n \"language_code\": \"en\"\n}'" }, { "lang": "Python", "source": "import base64\nfrom pathlib import Path\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.text_to_speech.convert_with_timestamps(\"voc_example\", text=\"Hello world.\", model_id=\"breeze-tts-2-multilingual\", output_format=\"wav\")\nPath(\"speech.wav\").write_bytes(base64.b64decode(result[\"audio_base64\"]))\nprint(result[\"word_timestamps\"])" }, { "lang": "TypeScript", "source": "import { writeFile } from \"node:fs/promises\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\nconst client = new BreezeBlueClient();\nconst result = await client.textToSpeech.convertWithTimestamps(\"voc_example\", { text: \"Hello world.\", modelId: \"breeze-tts-2-multilingual\" }, { outputFormat: \"wav\" });\nawait writeFile(\"speech.wav\", Buffer.from(result.audioBase64, \"base64\"));\nconsole.log(result.wordTimestamps);" } ] } }, "/v1/generation-jobs/{generation_job_id}": { "get": { "tags": [ "Text to Speech" ], "summary": "Get generation job", "description": "Get the status and result metadata for an asynchronous text-to-speech job.", "operationId": "generation_jobs_get", "parameters": [ { "name": "generation_job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Generation Job Id" }, "description": "Generation job identifier returned by async text-to-speech. See [Async jobs](https://docs.breezeblue.ai/guides/text-to-speech#async-jobs)." } ], "responses": { "200": { "description": "Generation job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerationJobResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nDownload audio after the job is ready.\nSubmit asynchronous generation requests.\nWait for jobs and save their audio.\n\n\n
" }, "x-breeze-api-name": "Get generation job", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/jobs-get", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The generation job does not exist or is not accessible." } ], "x-breeze-notes": [ "For a completed job, output_format echoes the requested format and audio_format describes the delivered encoding, sample rate, channel count and bitrate." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/generation-jobs/job_01hasync\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\njob = client.generation_jobs.get(\"job_01hasync\")\n\nprint(job[\"status\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst job = await client.generationJobs.get(\"job_01hasync\");\n\nconsole.log(job.status);" } ] } }, "/v1/generation-jobs/{generation_job_id}/audio": { "get": { "tags": [ "Text to Speech" ], "summary": "Download generation job audio", "description": "Download the audio for a completed asynchronous text-to-speech job.", "operationId": "generation_jobs_audio_download", "parameters": [ { "name": "generation_job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Generation Job Id" }, "description": "Generation job identifier returned by async text-to-speech. See [Async jobs](https://docs.breezeblue.ai/guides/text-to-speech#async-jobs)." } ], "responses": { "200": { "description": "Generated audio bytes.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "content-disposition": { "description": "Suggested inline filename.", "schema": { "type": "string" } }, "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "425": { "description": "HTTP 425 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying the generation audio request.", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nCheck readiness before downloading audio.\nChoose the encoding when submitting generation.\nFind, download, and remove past generations.\n\n\n
" }, "x-breeze-api-name": "Download generation job audio", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/jobs-audio", "x-breeze-errors": [ { "code": "GENERATION_NOT_READY", "description": "The generation job is still running; retry after the Retry-After interval." }, { "code": "GENERATION_FAILED", "description": "The generation job failed." }, { "code": "RESOURCE_NOT_FOUND", "description": "The generation job or audio does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/generation-jobs/job_01hasync/audio\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "from pathlib import Path\n\nfrom breeze_blue import save\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\naudio = client.generation_jobs.download_audio(\"job_01hasync\")\nsave(audio, Path(\"async.mp3\"))" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { save } from \"@breeze.blue/sdk/node\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst audio = await client.generationJobs.downloadAudio(\"job_01hasync\");\nawait save(audio, \"async.mp3\");" } ] } }, "/v1/text-to-speech/{voice_id}/stream": { "post": { "tags": [ "Text to Speech" ], "summary": "Stream text to speech", "description": "Stream synthesized audio as it is generated. For timing, see [Speech timing](https://docs.breezeblue.ai/guides/speech-timing); for one complete JSON response, use [Convert with timestamps](https://docs.breezeblue.ai/api-reference/text-to-speech/convert-with-timestamps).", "operationId": "tts_stream", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice ID to use for speech generation. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, { "name": "output_format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Format", "default": "pcm" }, "description": "Streaming audio encoding: pcm, mp3, or wav. Default: pcm. See [Output formats](https://docs.breezeblue.ai/concepts/output-format)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsRequest" } } } }, "responses": { "200": { "description": "Streaming audio bytes. The history-item-id header identifies the persisted generation.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "history-item-id": { "description": "History item ID for the generated audio.", "schema": { "type": "string" } }, "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose intent, emotion, and delivery.\nGenerate audio without word timing.\nStream audio with word timing.\nFollow HTTP, SDK, and async examples.\n\n\n
" }, "x-breeze-api-name": "Stream text to speech", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/stream", "x-breeze-errors": [ { "code": "VALIDATION_ERROR", "description": "The request body failed schema validation." }, { "code": "BAD_REQUEST", "description": "The request body or query parameter is not valid for this endpoint." }, { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." }, { "code": "GENERATION_CAPACITY_EXCEEDED", "description": "Generation capacity is temporarily exhausted." }, { "code": "UPSTREAM_GENERATION_ERROR", "description": "The downstream generation service failed." }, { "code": "UPSTREAM_TIMEOUT", "description": "The downstream generation service timed out." } ], "x-breeze-notes": [ "Use voice_settings.guidance_scale to adjust how strongly generation follows the prompt and reference voice. Accepted range: 1.0 to 10.0." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp/stream\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"text\": \"I can’t believe you brought him here!\",\n \"model_id\": \"breeze-tts-2\",\n \"instructions\": \"Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.\",\n \"voice_settings\": {\n \"guidance_scale\": 4.0\n }\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "from breeze_blue import stream\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\naudio = client.text_to_speech.stream(\n voice_id=\"voc_xeh3w54cqvnp\",\n text=\"I can’t believe you brought him here!\",\n instructions=\"Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.\",\n model_id=\"breeze-tts-2\",\n voice_settings={\"guidance_scale\": 4.0},\n)\nstream(audio)" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { stream } from \"@breeze.blue/sdk/node\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst audio = await client.textToSpeech.stream(\n \"voc_xeh3w54cqvnp\",\n {\n text: \"I can’t believe you brought him here!\",\n instructions: \"Say it softly and emotionally, with a hurt, disappointed tone, as if bringing him here broke your trust.\",\n modelId: \"breeze-tts-2\",\n voiceSettings: { guidanceScale: 4.0 },\n },\n);\nawait stream(audio);" } ] } }, "/v1/text-to-speech/{voice_id}/stream/with-timestamps": { "post": { "tags": [ "Text to Speech" ], "summary": "Stream speech with word timestamps", "description": "Stream speech and word timestamps as newline-delimited JSON (NDJSON). Each line contains audio, timing updates, or an error. See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing) for stream handling.", "operationId": "tts_stream_with_timestamps", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice ID. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, { "name": "output_format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Format", "default": "pcm" }, "description": "Audio encoding: pcm, mp3, or wav. Default: pcm. Decode audio_base64 before playing. See [Output formats](https://docs.breezeblue.ai/concepts/output-format)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsWithTimestampsRequest" } } } }, "responses": { "200": { "description": "NDJSON; each line is a speech timing chunk. A stream error instead contains an error object with code and message.", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/SpeechTimingChunkResponse" } } }, "headers": { "history-item-id": { "description": "History item ID for the generated audio.", "schema": { "type": "string" } }, "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose intent, emotion, and delivery.\nBuild captions with word timing.\nGet complete audio with word timing.\nChoose and decode an audio format.\n\n\n
" }, "x-breeze-api-name": "Stream speech with timestamps", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/stream-with-timestamps", "x-breeze-notes": [ "Supports BreezeBlue TTS 2 models. timestamp_mode is chunk (default) or lookahead. Timing follows the delivered audio, including speed and inserted segment pauses.", "For one complete JSON response, use [Convert with timestamps](https://docs.breezeblue.ai/api-reference/text-to-speech/convert-with-timestamps). See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing) for SDK and CLI examples." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp/stream/with-timestamps\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"text\": \"Hello world.\",\n \"model_id\": \"breeze-tts-2-multilingual\",\n \"language_code\": \"en\",\n \"timestamp_mode\": \"chunk\"\n}'" }, { "lang": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nwith client.text_to_speech.stream_with_timestamps(\"voc_example\", text=\"Hello world.\") as stream:\n for chunk in stream:\n print(chunk[\"word_timestamps\"])" }, { "lang": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\nconst client = new BreezeBlueClient();\nconst stream = await client.textToSpeech.streamWithTimestamps(\"voc_example\", { text: \"Hello world.\" });\nfor await (const chunk of stream) console.log(chunk.wordTimestamps);" } ] } }, "/v1/text-to-speech/{voice_id}/realtime-sessions": { "post": { "tags": [ "Text to Speech" ], "summary": "Create realtime TTS session", "description": "Create a short-lived browser-safe token for the realtime text-to-speech WebSocket. This HTTP operation only creates the session. Official SDKs and the CLI prefer the optional query-free `direct_websocket_url` and fall back to `websocket_url`; wait for `session.ready`, and then exchange turn events and binary PCM audio. While no turn is active, send `session.update` with non-empty `instructions` (up to 1,000 characters) and wait for `session.updated`; the confirmed instructions apply starting with the next turn. See the [Realtime TTS WebSocket guide](https://docs.breezeblue.ai/guides/realtime-text-to-speech) for complete raw WebSocket, SDK, browser playback, and CLI examples.", "operationId": "tts_realtime_sessions_create", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice ID to use for speech generation. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealtimeTtsSessionRequest" } } } }, "responses": { "200": { "description": "Realtime WebSocket session token and compatible transport URLs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealtimeTtsSessionResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose intent, emotion, and delivery.\nManage instructions across conversation turns.\nGenerate audio without word timing.\n\n\n
" }, "x-breeze-api-name": "Create realtime text to speech session", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/realtime-sessions", "x-breeze-errors": [ { "code": "AUTH_REQUIRED", "description": "Authentication is required." }, { "code": "AUTH_CONFIG_MISSING", "description": "Realtime session token signing is not configured." }, { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." }, { "code": "VALIDATION_ERROR", "description": "The request body failed schema validation." } ], "x-breeze-notes": [ "Use this endpoint from your backend before opening a browser WebSocket. Do not expose long-lived API keys in browser code.", "The associated WebSocket always streams pcm_s16le, 24000 Hz, mono, 16-bit audio and does not accept output_format.", "session.update is accepted only while the WebSocket session is idle. Only one update may be pending, and clients must wait for session.updated before starting the next turn.", "Sending session.update during an active turn returns a recoverable BAD_REQUEST without interrupting that turn; the previously confirmed instructions remain in effect." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp/realtime-sessions\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"model_id\": \"breeze-tts-2\",\n \"language_code\": \"en\",\n \"instructions\": \"Keep turns responsive and conversational.\",\n \"voice_settings\": {\n \"guidance_scale\": 4.0\n },\n \"inactivity_timeout_seconds\": 30,\n \"enable_logging\": true\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import asyncio\nfrom pathlib import Path\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nsession = client.text_to_speech.create_realtime_session(\n voice_id=\"voc_xeh3w54cqvnp\",\n model_id=\"breeze-tts-2\",\n)\n\n\nasync def main() -> None:\n async with client.text_to_speech.connect_realtime(\n voice_id=\"voc_xeh3w54cqvnp\",\n client_secret=session[\"client_secret\"],\n websocket_url=session[\"websocket_url\"],\n direct_websocket_url=session.get(\"direct_websocket_url\"),\n ) as connection:\n async def consume_audio() -> bytes:\n audio = bytearray()\n async for event in connection:\n if event[\"type\"] == \"audio\":\n audio.extend(event[\"audio\"])\n elif event[\"type\"] == \"error\":\n raise RuntimeError(event[\"message\"])\n elif event[\"type\"] == \"turn.done\":\n return bytes(audio)\n raise RuntimeError(\"Realtime session closed before turn.done\")\n\n consumer = asyncio.create_task(consume_audio())\n await connection.start_turn(\"turn_1\")\n await connection.append_text(\"Hello from Breeze.\")\n await connection.flush()\n await connection.end_turn()\n Path(\"out.pcm\").write_bytes(await consumer)\n\n\nasyncio.run(main())" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { writeFile } from \"node:fs/promises\";\n\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst session = await client.textToSpeech.realtime.createSession(\n \"voc_xeh3w54cqvnp\",\n { modelId: \"breeze-tts-2\" },\n);\n\nconst connection = await client.textToSpeech.realtime.connect(\n \"voc_xeh3w54cqvnp\",\n {\n clientSecret: session.clientSecret,\n websocketUrl: session.websocketUrl,\n directWebsocketUrl: session.directWebsocketUrl,\n },\n);\n\nconst consumer = (async () => {\n const pcmChunks: Uint8Array[] = [];\n for await (const message of connection) {\n if (message.type === \"audio\") pcmChunks.push(message.audio);\n if (message.type === \"error\") throw new Error(message.message);\n if (message.type === \"turn.done\") return pcmChunks;\n }\n throw new Error(\"Realtime session closed before turn.done\");\n})();\n\nconnection.startTurn(\"turn_1\");\nconnection.appendText(\"Hello from Breeze.\");\nconnection.flush();\nconnection.endTurn();\n\nconst pcmChunks = await consumer;\nawait writeFile(\n \"out.pcm\",\n Buffer.concat(pcmChunks.map((chunk) => Buffer.from(chunk))),\n);\nconnection.close();" } ] } }, "/v1/text-to-speech/enhance": { "post": { "tags": [ "Text to Speech" ], "summary": "Enhance text to speech instruction", "description": "Enhance a user-provided TTS instruction into clearer model guidance without changing the script or translating the instruction.", "operationId": "tts_enhance", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsEnhanceRequest" } } }, "required": true }, "responses": { "200": { "description": "Enhanced instruction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TtsEnhanceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose intent, emotion, and delivery.\nGenerate audio without word timing.\n\n\n
" }, "x-breeze-api-name": "Enhance text to speech instruction", "x-breeze-docs-group": "Text to Speech", "x-breeze-docs-href": "/docs/api-reference/text-to-speech/enhance", "x-breeze-errors": [ { "code": "VALIDATION_ERROR", "description": "The enhance payload failed validation." }, { "code": "LLM_CONFIG_NOT_FOUND", "description": "Instruction Enhance is not configured for the current environment." }, { "code": "UPSTREAM_GENERATION_ERROR", "description": "The upstream Instruction Enhance model failed." } ], "x-breeze-response-examples": [ { "label": "200 OK", "tone": "success", "lang": "json", "code": "{\n \"instruction\": \"Deliver the script in a calm, conversational style with clear pacing, gentle emphasis on key ideas, and natural pauses between sentences.\",\n \"language_code\": \"en\"\n}" } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/text-to-speech/enhance\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"instruction\": \"Make it warmer and more cinematic.\",\n \"language_code\": \"en\"\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nenhanced = client.text_to_speech.enhance(\n instruction=\"Make it warmer and more cinematic.\",\n language_code=\"en\",\n)\n\nprint(enhanced[\"instruction\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst enhanced = await client.textToSpeech.enhance({\n instruction: \"Make it warmer and more cinematic.\",\n languageCode: \"en\",\n});\n\nconsole.log(enhanced.instruction);" } ] } }, "/v1/voice-metadata/options": { "get": { "tags": [ "Voices" ], "summary": "List Voice Metadata options", "description": "Return the stable code sets accepted by Voice Metadata fields, including the complete language_code enum, the tone limit, and the language-to-accent cascade. Values are stable codes rather than localized display text.", "operationId": "voice_metadata_options", "responses": { "200": { "description": "Voice Metadata code options and constraints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceMetadataOptionsResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nFilter voices using the returned metadata codes.\nApply supported metadata to a saved voice.\nCheck language-dependent accent choices.\n\n\n
" }, "x-breeze-api-name": "List Voice Metadata options", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/metadata-options", "x-breeze-errors": [ { "code": "AUTH_REQUIRED", "description": "Authentication is required." } ], "x-breeze-notes": [ "Use accent_codes_by_language[language_code] to populate accent choices. An empty array means accent must be null." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voice-metadata/options\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\noptions = client.voices.metadata_options()\nprint(options[\"language_codes\"])\nprint(options[\"accent_codes_by_language\"][\"en\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst options = await client.voices.metadataOptions();\nconsole.log(options.languageCodes);\nconsole.log(options.accentCodesByLanguage.en);" } ] } }, "/v1/voices": { "get": { "tags": [ "Voices" ], "summary": "List voices", "description": "List or search every voice available to the authenticated account. Public-catalog searches keep semantic relevance first and use the daily global Trend rank only inside an equivalent relevance tier.", "operationId": "voices_list", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" }, "description": "Search public catalog voices by semantic and text relevance, and personal voices by name, description, or voice identifier." }, { "name": "language_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language Code", "enum": [ "af", "ar", "bg", "bn", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fr", "gl", "he", "hi", "hu", "id", "is", "it", "ja", "kn", "ko", "lt", "mr", "ms", "ne", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh" ] }, "description": "Only return voices whose saved audio language matches this supported ISO 639-1 two-letter language code. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, { "name": "primary_category_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "narration", "social-media", "ads-brand", "podcast", "learning", "support-agents", "roleplay", "gaming", "animation", "cinematic", "wellness", "stylized" ] }, { "type": "null" } ], "title": "Primary Category Code" }, "description": "Only return voices in this exact primary category. See [category codes](https://docs.breezeblue.ai/concepts/voices#category-codes)." }, { "name": "gender", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "male", "female", "neutral" ] } }, { "type": "null" } ], "title": "Gender" }, "description": "Repeat to match any supplied gender code. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, { "name": "age", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "child", "young", "middle_aged", "old" ] } }, { "type": "null" } ], "title": "Age" }, "description": "Repeat to match any supplied age code. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, { "name": "tone", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate" ] } }, { "type": "null" } ], "title": "Tone" }, "description": "Repeat to match voices containing any supplied tone code. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, { "name": "accent", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese", "mandarin_guangdong", "mandarin_yunnan" ] }, { "type": "null" } ], "title": "Accent" }, "description": "Filter by accent code. american also matches English voices whose accent is null. Cannot be combined with accent_mode=unmarked. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options), [accent codes](https://docs.breezeblue.ai/concepts/multilingual#voices-and-accents)." }, { "name": "accent_mode", "in": "query", "required": false, "schema": { "type": "string", "default": "all", "title": "Accent Mode", "enum": [ "all", "unmarked" ] }, "description": "all (default) applies no null-only filter. unmarked returns voices whose accent is null; combine with language_code=zh to find Mandarin voices. Cannot be combined with accent." }, { "name": "origin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin" }, "description": "Optional origin filter. Accepted values: designed, cloned." }, { "name": "voice_type", "in": "query", "required": false, "schema": { "type": "string", "default": "all", "title": "Voice Type" }, "description": "Voice source filter. Accepted values: all, default, personal." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "default": "created_at_unix", "title": "Sort" }, "description": "Sort field for non-search listings. Accepted values: created_at_unix, name, trend. trend is available only with voice_type=default. Eligible voices absent from the daily snapshot follow ranked voices; pagination pins the snapshot and initial supplemental candidates." }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Sort Direction" }, "description": "Sort direction for non-search listings. Accepted values: asc, desc. The default is desc. For trend, desc means most popular first." }, { "name": "next_page_token", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Page Token" }, "description": "Pagination token from the previous response. Keep the same filters." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "description": "Page number for offset-based navigation." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Page Size" }, "description": "Number of records to return per page." }, { "name": "favorites_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Favorites Only" }, "description": "Only return voices favorited by the authenticated account." }, { "name": "tags", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "title": "Tags" }, "description": "Return voices matching all supplied tags, ignoring case. See [Tags and favorites](https://docs.breezeblue.ai/concepts/voices#tags-and-favorites)." } ], "responses": { "200": { "description": "Paginated voice list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceListResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nInspect a selected voice before synthesis.\nDiscover valid filter and metadata values.\nGenerate speech with the selected voice.\n\n\n
" }, "x-breeze-api-name": "List voices", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/list", "x-breeze-errors": [ { "code": "BAD_REQUEST", "description": "One of the filter values is not valid for this endpoint." }, { "code": "AUTH_REQUIRED", "description": "Authentication is required." }, { "code": "INTERNAL_ERROR", "description": "The Daily Trend snapshot is temporarily unavailable." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voices\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nvoices = client.voices.search(search=\"calm documentary narrator\")\nfor voice in voices[\"voices\"]:\n print(voice[\"voice_id\"], voice[\"name\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst voices = await client.voices.search({ search: \"calm documentary narrator\" });\nfor (const voice of voices.voices) {\n console.log(voice.voiceId, voice.name);\n}" } ] } }, "/v1/voices/random": { "get": { "tags": [ "Voices" ], "summary": "Get a random voice", "description": "Return one random voice visible to the authenticated user. Optionally narrow the pool by language or voice source. Use the returned voice_id with text-to-speech endpoints.", "operationId": "voices_random", "parameters": [ { "name": "language_code", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language Code", "enum": [ "af", "ar", "bg", "bn", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fr", "gl", "he", "hi", "hu", "id", "is", "it", "ja", "kn", "ko", "lt", "mr", "ms", "ne", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh" ] }, "description": "Only pick from voices whose saved audio language matches this supported ISO 639-1 two-letter language code. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, { "name": "voice_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Type", "enum": [ "default", "personal" ] }, "description": "Voice source filter. Accepted values: default, personal. Omit to pick from both personal voices and the public catalog." } ], "responses": { "200": { "description": "Random voice metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nBrowse and choose a voice explicitly.\nInspect the returned voice identity.\nUse the returned voice ID for speech.\n\n\n
" }, "x-breeze-api-name": "Get a random voice", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/random", "x-breeze-errors": [ { "code": "BAD_REQUEST", "description": "One of the filter values is not valid for this endpoint." }, { "code": "RESOURCE_NOT_FOUND", "description": "No accessible voice matches the requested filters." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voices/random\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nvoice = client.voices.random()\n\nprint(voice[\"voice_id\"], voice[\"name\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst voice = await client.voices.random();\n\nconsole.log(voice.voiceId, voice.name);" } ] } }, "/v1/voices/{voice_id}": { "get": { "tags": [ "Voices" ], "summary": "Get a voice", "description": "Get voice metadata by voice_id.", "operationId": "voices_get", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "responses": { "200": { "description": "Voice metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nGenerate speech with this voice.\nRead saved generation settings.\nEdit a voice you can manage.\n\n\n
" }, "x-breeze-api-name": "Get a voice", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/get", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nvoice = client.voices.get(\"voc_xeh3w54cqvnp\")\n\nprint(voice[\"voice_id\"], voice[\"name\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst voice = await client.voices.get(\"voc_xeh3w54cqvnp\");\n\nconsole.log(voice.voiceId, voice.name);" } ] }, "patch": { "tags": [ "Voices" ], "summary": "Edit a voice", "description": "Update a saved voice. Metadata values are stable lowercase codes. Omit a metadata field to preserve it; send an empty string to clear gender, age, or accent, and send one empty tone field to clear tone. When language_code changes and the existing accent is no longer valid, Breeze clears accent automatically. Replacing reference audio requires the new sample's language_code unless Breeze can detect it.", "operationId": "voices_edit", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Saved voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/VoicesEditRequestBody" } } } }, "responses": { "200": { "description": "Update status. An accepted publication review is not yet public; poll the voice for its outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceEditStatusResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose valid language, accent, and tone codes.\nRead the saved voice details.\nOrganize the voice with personal tags.\n\n\n
" }, "x-breeze-api-name": "Edit a voice", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/edit", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not owned by the current account." }, { "code": "VOICE_CLONE_NO_SPEECH_DETECTED", "description": "No clear speech was found in the replacement reference audio." }, { "code": "VOICE_CLONE_REFERENCE_TOO_QUIET", "description": "The replacement reference audio is too quiet for speech to be detected." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --form \"name=Brand Narrator v2\" \\\n --form \"description=Updated voice description for the saved clone.\" \\\n --form \"files=@sample.wav;type=audio/wav\"" }, { "lang": "Python", "label": "Python SDK", "source": "from pathlib import Path\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nclient.voices.edit(\n \"voc_xeh3w54cqvnp\",\n name=\"Brand Narrator v2\",\n description=\"Updated voice description for the saved clone.\",\n file=Path(\"sample.wav\"),\n)" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { readFile } from \"node:fs/promises\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nawait client.voices.edit(\"voc_xeh3w54cqvnp\", {\n name: \"Brand Narrator v2\",\n description: \"Updated voice description for the saved clone.\",\n file: {\n data: await readFile(\"sample.wav\"),\n filename: \"sample.wav\",\n contentType: \"audio/wav\",\n },\n});" } ] }, "delete": { "tags": [ "Voices" ], "summary": "Delete a voice", "description": "Soft-delete a saved voice.", "operationId": "voices_delete", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "responses": { "200": { "description": "Delete status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericStatusResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nVerify the voice before deleting it.\nChoose a replacement voice.\nUnderstand voice identity, metadata, and settings.\n\n\n
" }, "x-breeze-api-name": "Delete a voice", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/delete", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not owned by the current account." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nclient.voices.delete(\"voc_xeh3w54cqvnp\")" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nawait client.voices.delete(\"voc_xeh3w54cqvnp\");" } ] } }, "/v1/voices/{voice_id}/tags": { "put": { "tags": [ "Voices" ], "summary": "Update effective voice tags", "description": "Replace owner tags or a favoriting account's complete personal override. An empty personal array resumes inheritance from the owner.", "operationId": "voices_tags_update", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceTagsUpdateRequest" } } } }, "responses": { "200": { "description": "Updated voice metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nFind voices using tag filters.\nMark a voice for quick access.\nUnderstand voice identity, metadata, and settings.\n\n\n
" }, "x-breeze-api-name": "Update voice tags", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/update-tags", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PUT \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp/tags\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" } ] } }, "/v1/voices/{voice_id}/favorite": { "put": { "tags": [ "Voices" ], "summary": "Favorite a voice", "description": "Create or reactivate the authenticated account's favorite relation.", "operationId": "voices_favorite", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "responses": { "200": { "description": "Updated voice metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nRetrieve your favorite voices.\nRemove a voice from favorites.\nGroup voices with personal tags.\n\n\n
" }, "x-breeze-api-name": "Favorite a voice", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/favorite", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PUT \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp/favorite\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" } ] }, "delete": { "tags": [ "Voices" ], "summary": "Unfavorite a voice", "description": "Soft-delete the favorite relation while retaining its personal tag override.", "operationId": "voices_unfavorite", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "responses": { "200": { "description": "Updated voice metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nAdd the voice back to favorites.\nBrowse the remaining favorites.\n\n\n
" }, "x-breeze-api-name": "Unfavorite a voice", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/unfavorite", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp/favorite\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" } ] } }, "/v1/voices/{voice_id}/settings": { "get": { "tags": [ "Voices" ], "summary": "Get voice settings", "description": "Get saved voice_settings for a voice.", "operationId": "voices_settings_get", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "responses": { "200": { "description": "Voice settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSettingsResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChange saved generation defaults.\nOverride settings for an individual request.\nUnderstand voice identity, metadata, and settings.\n\n\n
" }, "x-breeze-api-name": "Get voice settings", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/settings", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp/settings\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nsettings = client.voices.get_settings(\"voc_xeh3w54cqvnp\")\n\nprint(settings)" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst settings = await client.voices.getSettings(\"voc_xeh3w54cqvnp\");\n\nconsole.log(settings);" } ] }, "patch": { "tags": [ "Voices" ], "summary": "Update voice settings", "description": "Update voice_settings. At least one field is required.", "operationId": "voices_settings_update", "parameters": [ { "name": "voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Voice Id" }, "description": "Voice identifier returned by GET /v1/voices. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSettingsPayload" } } } }, "responses": { "200": { "description": "Updated voice settings.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceSettingsResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nRead back the saved settings.\nTry the settings on a passage.\nDirect delivery without changing voice identity.\n\n\n
" }, "x-breeze-api-name": "Update voice settings", "x-breeze-docs-group": "Voices", "x-breeze-docs-href": "/docs/api-reference/voices/settings-edit", "x-breeze-errors": [ { "code": "BAD_REQUEST", "description": "At least one voice_settings field must be provided." }, { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/voices/voc_xeh3w54cqvnp/settings\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"guidance_scale\": 1.4\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nsettings = client.voices.edit_settings(\n \"voc_xeh3w54cqvnp\",\n guidance_scale=1.4,\n)\n\nprint(settings)" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst settings = await client.voices.editSettings(\"voc_xeh3w54cqvnp\", {\n guidanceScale: 1.4,\n});\n\nconsole.log(settings);" } ] } }, "/v1/voice-previews/clone": { "post": { "tags": [ "Voice Previews" ], "summary": "Create clone preview", "description": "Upload one reference sample and create a temporary voice clone preview. Breeze detects the spoken language and automatically generates the preview script in that language. Custom text, instructions, and language hints are not accepted.", "operationId": "voice_previews_clone", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/VoicePreviewsCloneRequestBody" } } } }, "responses": { "200": { "description": "Generated clone preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceClonePreviewResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "HTTP 502 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nPrepare reference audio and audition the result.\nDownload the completed preview.\nSave the preview before using it for TTS.\n\n\n
" }, "x-breeze-api-name": "Create clone preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/clone", "x-breeze-errors": [ { "code": "BAD_REQUEST", "description": "The upload format or request shape is not valid for this endpoint." }, { "code": "VOICE_CLONE_NO_SPEECH_DETECTED", "description": "No clear speech was found in the reference audio: it may hold only music, noise, or silence." }, { "code": "VOICE_CLONE_REFERENCE_TOO_QUIET", "description": "The reference audio is too quiet for speech to be detected." }, { "code": "VOICE_CLONE_REFERENCE_LANGUAGE_UNSUPPORTED", "description": "The language spoken in the reference audio is not supported for cloning." }, { "code": "VALIDATION_ERROR", "description": "Reference audio analysis could not run; retry the request." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." }, { "code": "VOICE_CLONE_FAILED", "description": "Voice cloning failed." }, { "code": "UPSTREAM_GENERATION_ERROR", "description": "The generation service failed." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/voice-previews/clone\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --form \"name=Brand Narrator\" \\\n --form \"description=Clean studio narration sample.\" \\\n --form \"files=@sample.wav;type=audio/wav\"" }, { "lang": "Python", "label": "Python SDK", "source": "from pathlib import Path\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\npreview = client.voices.create_clone_preview(\n name=\"Brand Narrator\",\n file=Path(\"sample.wav\"),\n description=\"Clean studio narration sample.\",\n)\n\nprint(preview[\"generated_voice_id\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { readFile } from \"node:fs/promises\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst preview = await client.voices.createClonePreview({\n name: \"Brand Narrator\",\n file: {\n data: await readFile(\"sample.wav\"),\n filename: \"sample.wav\",\n contentType: \"audio/wav\",\n },\n description: \"Clean studio narration sample.\",\n});\n\nconsole.log(preview.generatedVoiceId);" } ] } }, "/v1/voice-previews/design": { "post": { "tags": [ "Voice Previews" ], "summary": "Create design previews", "description": "Generate temporary voice previews from a text description.", "operationId": "voice_previews_design", "parameters": [ { "name": "output_format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Format", "default": "mp3" }, "description": "Audio format for the embedded preview payloads. Supported values: mp3, wav, flac, pcm, aac, opus. Default: mp3. See [Output formats](https://docs.breezeblue.ai/concepts/output-format)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceDesignRequest" } } } }, "responses": { "200": { "description": "Generated voice previews.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceDesignResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "HTTP 502 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nWrite a voice description and preview script.\nStream one PCM preview.\nSave a reusable voice for TTS.\nChoose intent, emotion, and delivery.\n\n\n
" }, "x-breeze-api-name": "Create design previews", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/design", "x-breeze-errors": [ { "code": "BAD_REQUEST", "description": "The request body or output option is not valid for this endpoint." }, { "code": "VALIDATION_ERROR", "description": "The request body failed validation." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." }, { "code": "VOICE_DESIGN_FAILED", "description": "Voice design failed." }, { "code": "UPSTREAM_GENERATION_ERROR", "description": "The generation service failed." } ], "x-breeze-notes": [ "Supported optional controls: preview_count, guidance_scale, model_id. preview_count defaults to 1 and accepts values from 1 to 3. guidance_scale accepts values from 1.0 to 10.0. When you pass guidance_scale, that exact value is used; when you omit it, Breeze picks a random value between 1.0 and 10.0 for the request." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/voice-previews/design\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"voice_description\": \"Warm, intimate narrator with crisp diction.\",\n \"text\": \"Welcome to Breeze Blue.\",\n \"guidance_scale\": 4.0,\n \"preview_count\": 3\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\ndesign = client.voices.create_design_preview(\n voice_description=\"Warm, intimate narrator with crisp diction.\",\n text=\"Welcome to Breeze Blue.\",\n guidance_scale=4.0,\n preview_count=3,\n)\n\nfor preview in design[\"previews\"]:\n print(preview[\"generated_voice_id\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst design = await client.voices.createDesignPreview({\n voiceDescription: \"Warm, intimate narrator with crisp diction.\",\n text: \"Welcome to Breeze Blue.\",\n guidanceScale: 4.0,\n previewCount: 3,\n});\n\nfor (const preview of design.previews) {\n console.log(preview.generatedVoiceId);\n}" } ] } }, "/v1/voice-previews/design/stream": { "post": { "tags": [ "Voice Previews" ], "summary": "Stream a design preview", "description": "Generate one temporary voice preview and stream its audio while it is being created.", "operationId": "voice_previews_design_stream", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceDesignStreamRequest" } } }, "required": true }, "responses": { "200": { "description": "Live 24 kHz mono signed 16-bit little-endian PCM audio. A clean EOF means the preview is persisted and can be saved.", "content": { "audio/pcm": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "history-item-id": { "description": "History item ID for the generated audio.", "schema": { "type": "string" } }, "generated-voice-id": { "description": "Temporary generated voice ID. It can be saved after the stream finishes cleanly.", "schema": { "type": "string" } }, "x-breeze-audio-codec": { "description": "Audio codec. Fixed to pcm_s16le.", "schema": { "type": "string", "enum": [ "pcm_s16le" ] } }, "x-breeze-sample-rate": { "description": "Audio sample rate in hertz. Fixed to 24000.", "schema": { "type": "integer", "enum": [ 24000 ] } }, "x-breeze-channels": { "description": "Audio channel count. Fixed to mono (1).", "schema": { "type": "integer", "enum": [ 1 ] } }, "x-breeze-sample-width-bytes": { "description": "PCM sample width in bytes. Fixed to 2.", "schema": { "type": "integer", "enum": [ 2 ] } }, "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "HTTP 502 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nWrite a voice description and preview script.\nGenerate and compare encoded previews.\nSave a reusable voice for TTS.\nChoose intent, emotion, and delivery.\n\n\n
" }, "x-breeze-api-name": "Stream a design preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/design-stream", "x-breeze-errors": [ { "code": "BAD_REQUEST", "description": "The request is not valid for this endpoint." }, { "code": "VALIDATION_ERROR", "description": "The request body failed validation." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." }, { "code": "VOICE_DESIGN_FAILED", "description": "Voice design failed." }, { "code": "UPSTREAM_GENERATION_ERROR", "description": "The generation service failed." }, { "code": "UPSTREAM_TIMEOUT", "description": "The generation service timed out." } ], "x-breeze-notes": [ "This endpoint always generates exactly one preview. preview_count is not accepted.", "The response format is fixed to 24 kHz mono pcm_s16le. output_format is not accepted.", "If the connection ends with an error, discard partial audio and do not save the generated_voice_id." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/voice-previews/design/stream\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"voice_description\": \"Warm, intimate narrator with crisp diction.\",\n \"text\": \"Welcome to Breeze Blue.\",\n \"language_code\": \"en\",\n \"guidance_scale\": 4.0\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "from breeze_blue import stream\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\naudio = client.voices.stream_design_preview(\n voice_description=\"Warm, intimate narrator with crisp diction.\",\n text=\"Welcome to Breeze Blue.\",\n guidance_scale=4.0,\n)\nprint(audio.generated_voice_id)\nstream(audio)" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { stream } from \"@breeze.blue/sdk/node\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst audio = await client.voices.streamDesignPreview({\n voiceDescription: \"Warm, intimate narrator with crisp diction.\",\n text: \"Welcome to Breeze Blue.\",\n guidanceScale: 4.0,\n});\nconsole.log(audio.generatedVoiceId);\nawait stream(audio);" } ] } }, "/v1/voice-previews/remix/presets": { "get": { "tags": [ "Voice Previews" ], "summary": "List remix presets", "description": "Browse curated voice changes and their sample recordings. Use a preset ID when preparing or generating a remix. Browsing does not spend credits.", "operationId": "voice_previews_remix_presets", "responses": { "200": { "description": "Voice Remix preset catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceRemixPresetsResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose, audition, and save a voice change.\nPrepare a preset or custom description.\n\n\n
" }, "x-breeze-api-name": "List remix presets", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/remix-presets", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voice-previews/remix/presets\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\npresets = client.voices.list_remix_presets()\nprint(presets[\"presets\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst catalog = await client.voices.listRemixPresets();\nconsole.log(catalog.presets);" } ] } }, "/v1/voice-previews/remix/prepare": { "post": { "tags": [ "Voice Previews" ], "summary": "Prepare remix preview", "description": "Prepare an instruction and matching audition script in the source voice's language. Reuse the returned token to compare candidates with the same performance. This step does not create audio or reserve generation credits.", "operationId": "voice_previews_remix_prepare", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceRemixPrepareRequest" } } }, "required": true }, "responses": { "200": { "description": "Prepared remix performance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceRemixPreparationResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "502": { "description": "HTTP 502 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nGenerate a candidate using the prepared performance.\nCompare strengths with a shared preparation.\n\n\n
" }, "x-breeze-api-name": "Prepare remix preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/remix-prepare", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The source voice is not available for remixing." }, { "code": "VALIDATION_ERROR", "description": "Provide a prompt or valid preset ID and a usable source voice." }, { "code": "VOICE_REMIX_FAILED", "description": "Preparation failed; no generation credits were reserved." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/voice-previews/remix/prepare\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"voice_id\": \"voc_xeh3w54cqvnp\",\n \"prompt\": \"Make the voice older and softer.\"\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nprepared = client.voices.prepare_remix_preview(\n voice_id=\"voc_xeh3w54cqvnp\",\n prompt=\"Make the voice older and softer.\",\n)\nprint(prepared[\"preparation_token\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst prepared = await client.voices.prepareRemixPreview({\n voiceId: \"voc_xeh3w54cqvnp\",\n prompt: \"Make the voice older and softer.\",\n});\nconsole.log(prepared.preparationToken);" } ] } }, "/v1/voice-previews/remix": { "post": { "tags": [ "Voice Previews" ], "summary": "Create remix preview", "description": "Create one same-language voice candidate from an owned or official voice and a prompt. Poll the durable job, audition its preview, then save a private new voice. The source voice is never changed.", "operationId": "voice_previews_remix", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceRemixPreviewRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted background voice remix job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceRemixPreviewJobResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "HTTP 502 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nGenerate, audition, and save remixed previews.\nPoll the returned generation job.\nCheck voice language and metadata codes.\n\n\n
" }, "x-breeze-api-name": "Create remix preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/remix", "x-breeze-errors": [ { "code": "VALIDATION_ERROR", "description": "The request body failed validation." }, { "code": "BAD_REQUEST", "description": "The reference language is not supported by the selected model." }, { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." }, { "code": "FORBIDDEN", "description": "The account has no remaining saved voice slots." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." }, { "code": "VOICE_REMIX_FAILED", "description": "Voice remix failed." } ], "x-breeze-notes": [ "Each successful candidate is billed at the Voice Design candidate price; failures release the reservation.", "Send Idempotency-Key (1–128 characters) to replay the same request without creating or charging another candidate. Different input with the same key returns CONFLICT.", "A concurrent submission of the same key returns CONFLICT; retry that key to retrieve the accepted job.", "The voice must have a valid matching audio and transcript. Language and model are resolved by the server.", "To compare three strengths, prepare once and submit three candidates at 4, 6 and 8, each with its own idempotency key. Each candidate is billed separately." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/voice-previews/remix\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"voice_id\": \"voc_xeh3w54cqvnp\",\n \"prompt\": \"Make the voice older and softer.\",\n \"guidance_scale\": 4\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\njob = client.voices.create_remix_preview(\n voice_id=\"voc_xeh3w54cqvnp\",\n prompt=\"Make the voice older and softer.\",\n)\n\nprint(job[\"generation_job_id\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst job = await client.voices.createRemixPreview({\n voiceId: \"voc_xeh3w54cqvnp\",\n prompt: \"Make the voice older and softer.\",\n});\n\nconsole.log(job.generationJobId);" } ] } }, "/v1/voice-previews/remix/{generation_job_id}": { "get": { "tags": [ "Voice Previews" ], "summary": "Get remix preview", "description": "Get the status of a voice remix job. Once status is ready, generated_voice_id can be downloaded and saved like any other voice preview.", "operationId": "voice_previews_remix_status", "parameters": [ { "name": "generation_job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Generation Job Id" }, "description": "Job identifier returned by POST /v1/voice-previews/remix. See [Async jobs](https://docs.breezeblue.ai/guides/text-to-speech#async-jobs)." } ], "responses": { "200": { "description": "Voice remix job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceRemixPreviewStatusResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nDownload the completed remixed preview.\nSave the chosen remixed voice.\nGenerate, audition, and save remixed previews.\n\n\n
" }, "x-breeze-api-name": "Get remix preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/remix-status", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The voice remix job does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voice-previews/remix/job_01hasync\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\njob = client.voices.get_remix_preview(\"job_01hasync\")\n\nif job[\"status\"] == \"ready\":\n print(job[\"generated_voice_id\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst job = await client.voices.getRemixPreview(\"job_01hasync\");\n\nif (job.status === \"ready\") {\n console.log(job.generatedVoiceId);\n}" } ] } }, "/v1/voice-previews/localize": { "post": { "tags": [ "Voice Previews" ], "summary": "Create localize preview", "description": "Localize an existing voice into another speaking language and return a background job. Breeze keeps the source timbre and picks the preview script for the target language; poll the job and save the preview it produces.", "operationId": "voice_previews_localize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceLocalizePreviewRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted background voice localization job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceLocalizePreviewJobResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "HTTP 429 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nGenerate, audition, and save localized previews.\nPoll the returned localization job.\nCheck target language and accent codes.\n\n\n
" }, "x-breeze-api-name": "Create localize preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/localize", "x-breeze-errors": [ { "code": "VALIDATION_ERROR", "description": "The request body failed validation." }, { "code": "BAD_REQUEST", "description": "The target language is not supported by the selected model." }, { "code": "RESOURCE_NOT_FOUND", "description": "The voice_id does not exist or is not accessible." }, { "code": "FORBIDDEN", "description": "The account has no remaining saved voice slots." }, { "code": "GENERATION_CONCURRENCY_EXCEEDED", "description": "Your plan's concurrent generation limit was reached. Please retry shortly." }, { "code": "VOICE_LOCALIZE_FAILED", "description": "Voice localization failed." } ], "x-breeze-notes": [ "Localization is billed at the voice clone rate when the job is accepted.", "A localized voice occupies a saved voice slot, so the request is rejected when the library is full." ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/voice-previews/localize\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"voice_id\": \"voc_xeh3w54cqvnp\",\n \"language_code\": \"es\",\n \"name\": \"Brand Narrator (Spanish)\"\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\njob = client.voices.create_localize_preview(\n voice_id=\"voc_xeh3w54cqvnp\",\n language_code=\"es\",\n name=\"Brand Narrator (Spanish)\",\n)\n\nprint(job[\"generation_job_id\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst job = await client.voices.createLocalizePreview({\n voiceId: \"voc_xeh3w54cqvnp\",\n languageCode: \"es\",\n name: \"Brand Narrator (Spanish)\",\n});\n\nconsole.log(job.generationJobId);" } ] } }, "/v1/voice-previews/localize/{generation_job_id}": { "get": { "tags": [ "Voice Previews" ], "summary": "Get localize preview", "description": "Get the status of a voice localization job. Once status is ready, generated_voice_id can be downloaded and saved like any other voice preview.", "operationId": "voice_previews_localize_status", "parameters": [ { "name": "generation_job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Generation Job Id" }, "description": "Job identifier returned by POST /v1/voice-previews/localize. See [Async jobs](https://docs.breezeblue.ai/guides/text-to-speech#async-jobs)." } ], "responses": { "200": { "description": "Voice localization job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoiceLocalizePreviewStatusResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nDownload the completed localized preview.\nSave the chosen localized voice.\nGenerate, audition, and save localized previews.\n\n\n
" }, "x-breeze-api-name": "Get localize preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/localize-status", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The voice localization job does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voice-previews/localize/job_01hasync\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\njob = client.voices.get_localize_preview(\"job_01hasync\")\n\nif job[\"status\"] == \"ready\":\n print(job[\"generated_voice_id\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst job = await client.voices.getLocalizePreview(\"job_01hasync\");\n\nif (job.status === \"ready\") {\n console.log(job.generatedVoiceId);\n}" } ] } }, "/v1/voice-previews/{generated_voice_id}/stream": { "get": { "tags": [ "Voice Previews" ], "summary": "Download completed voice preview", "description": "Download a completed voice preview before saving it. This endpoint does not provide generation-time streaming.", "operationId": "voice_previews_stream", "parameters": [ { "name": "generated_voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Generated Voice Id" }, "description": "Preview ID from Voice Design, Clone, Remix or Localize. Asynchronous candidates must be ready. See [Saving a preview](https://docs.breezeblue.ai/guides/voice-design#persist-the-voice)." }, { "name": "output_format", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Output Format", "default": "mp3" }, "description": "Output format for the preview. Supported values: mp3, wav, flac, pcm, aac, opus. Default: mp3. See [Output formats](https://docs.breezeblue.ai/concepts/output-format)." } ], "responses": { "200": { "description": "Binary audio preview.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nSave an auditioned preview as a voice.\nGenerate previews from a description.\nGenerate a preview from reference audio.\n\n\n
" }, "x-breeze-api-name": "Download completed voice preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/stream", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The generated voice preview does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/voice-previews/gvi_01hpreview/stream\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "from pathlib import Path\n\nfrom breeze_blue import save\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\naudio = client.voices.stream_preview(\n generated_voice_id=\"gvi_01hpreview\",\n)\nsave(audio, Path(\"preview.mp3\"))" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { save } from \"@breeze.blue/sdk/node\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst audio = await client.voices.streamPreview(\"gvi_01hpreview\");\nawait save(audio, \"preview.mp3\");" } ] } }, "/v1/voice-previews/{generated_voice_id}/save": { "post": { "tags": [ "Voice Previews" ], "summary": "Save voice preview", "description": "Save a generated preview as a private voice. Voice Metadata values are stable lowercase codes; tone accepts up to three distinct codes. language_code is required. accent is available only for en and zh and must match language_code.", "operationId": "voice_previews_save", "parameters": [ { "name": "generated_voice_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Generated Voice Id" }, "description": "Preview ID returned by a voice preview creation endpoint. See [Saving a preview](https://docs.breezeblue.ai/guides/voice-design#persist-the-voice)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveVoicePreviewRequest" } } } }, "responses": { "200": { "description": "Saved voice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedVoiceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nGenerate, audition, and save previews.\nWrite a voice description and preview script.\nGenerate audio without word timing.\n\n\n
" }, "x-breeze-api-name": "Save voice preview", "x-breeze-docs-group": "Voice Previews", "x-breeze-docs-href": "/docs/api-reference/voice-previews/save", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The generated_voice_id does not exist or is not owned by the current account." }, { "code": "FORBIDDEN", "description": "The account has no remaining saved voice slots." }, { "code": "VOICE_CLONE_REFERENCE_LANGUAGE_MISMATCH", "description": "language_code differs from the language detected in the clone preview's reference audio; the response meta names both." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/voice-previews/gvi_01hpreview/save\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"voice_name\": \"Brand Narrator\"\n}'" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nvoice = client.voices.save_preview(\n generated_voice_id=\"gvi_01hpreview\",\n voice_name=\"Brand Narrator\",\n language_code=\"en\",\n)\n\nprint(voice[\"voice_id\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst voice = await client.voices.savePreview({\n generatedVoiceId: \"gvi_01hpreview\",\n voiceName: \"Brand Narrator\",\n languageCode: \"en\",\n});\n\nconsole.log(voice.voiceId);" } ] } }, "/v1/balance": { "get": { "tags": [ "Account" ], "summary": "Get account balance", "description": "Get the current credit balance and recent top-ups.", "operationId": "account_balance_get", "responses": { "200": { "description": "Account balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nInspect how generation used your credits.\nCheck plan and concurrency limits.\nUnderstand shared credits and generation costs.\n\n\n
" }, "x-breeze-api-name": "Get account balance", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/balance", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/balance\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nbalance = client.account.balance()\n\nprint(balance[\"balance\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst balance = await client.account.balance();\n\nconsole.log(balance.balance);" } ] } }, "/v1/entitlements": { "get": { "tags": [ "Account" ], "summary": "Get account entitlements", "description": "Get the current plan code and generation concurrency limits.", "operationId": "account_entitlements_get", "responses": { "200": { "description": "Account entitlements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementsResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nHandle concurrency limits and rejected requests.\nCheck available credits before generation.\nUnderstand shared credits and generation costs.\n\n\n
" }, "x-breeze-api-name": "Get account entitlements", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/entitlements", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/entitlements\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" } ] } }, "/v1/usage": { "get": { "tags": [ "Account" ], "summary": "Get usage metering", "description": "Get aggregated usage with daily buckets and recent requests.", "operationId": "account_usage_list", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 90, "minimum": 1, "default": 30, "title": "Days" }, "description": "Window length in days (1–90)." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" }, "description": "Keyword filter across endpoint, model, action code, key id, key name, and key prefix." }, { "name": "method", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method" }, "description": "Filter by HTTP method." }, { "name": "api_key_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Api Key Id" }, "description": "Filter by public API key identifier (key_...)." }, { "name": "status_class", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Class" }, "description": "Filter by HTTP status class: 2xx, 4xx, 5xx, or other." }, { "name": "client_type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Client Type" }, "description": "Filter by client type: api, sdk, or cli." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" }, "description": "Inclusive start date (YYYY-MM-DD)." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" }, "description": "Inclusive end date (YYYY-MM-DD)." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "description": "Page number for the request log." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" }, "description": "Rows per page." } ], "responses": { "200": { "description": "Aggregated usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nCheck remaining account credits.\nInspect individual generation results.\nUnderstand shared credits and generation costs.\n\n\n
" }, "x-breeze-api-name": "Get usage metering", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/usage", "x-breeze-response-examples": [ { "label": "200 OK", "tone": "success", "lang": "json", "code": "{\n \"window_days\": 30,\n \"summary\": {\n \"request_count\": 1280,\n \"total_text_characters\": 184320,\n \"total_billable_units\": 184320,\n \"total_cost\": 184.320,\n \"total_cost_millicredits\": 184320\n },\n \"total\": 2,\n \"page\": 1,\n \"page_size\": 20,\n \"daily\": [\n { \"date\": \"2026-04-01\", \"request_count\": 42 },\n { \"date\": \"2026-04-02\", \"request_count\": 65 }\n ],\n \"items\": [\n {\n \"id\": \"use_01h...\",\n \"endpoint\": \"/v1/text-to-speech/voc_01h...\",\n \"method\": \"POST\",\n \"status\": 200,\n \"model\": \"breeze-tts-2\",\n \"billable_units\": 128,\n \"cost\": 0.128,\n \"cost_millicredits\": 128,\n \"latency_ms\": null,\n \"duration_ms\": 2500,\n \"first_audio_chunk_ms\": null,\n \"request_duration_ms\": 842,\n \"trace_id\": \"trace_01h...\",\n \"request_id\": \"req_01h...\",\n \"text_characters\": 128,\n \"action_code\": \"developer_text_to_speech\",\n \"created_at\": \"2026-04-02T10:15:30Z\"\n }\n ]\n}" } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/usage\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nusage = client.account.usage(days=30, api_key_id=\"key_01hprod\", client_type=\"sdk\")\n\nprint(usage[\"summary\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst usage = await client.account.usage({\n days: 30,\n apiKeyId: \"key_01hprod\",\n clientType: \"sdk\",\n});\n\nconsole.log(usage.summary);" } ] } }, "/v1/api-keys": { "get": { "tags": [ "Account" ], "summary": "List API keys", "description": "List API keys for the signed-in user. API keys are not accepted on this endpoint.", "operationId": "api_keys_list", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" }, "description": "Filter by name or prefix." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" }, "description": "Filter by status: active or disabled." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "description": "Page number." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Page Size" }, "description": "Keys per page." } ], "responses": { "200": { "description": "API key list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nCreate a key for an integration.\nInspect the key authenticating an API request.\nChoose API-key or browser-session authentication.\n\n\n
" }, "x-breeze-api-name": "List API keys", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-list", "x-breeze-auth": "browser-session", "x-sdk-exclude": true }, "post": { "tags": [ "Account" ], "summary": "Create an API key", "description": "Create an API key and return the one-time secret. Each account can keep up to 50 keys, including disabled and CLI device keys.", "operationId": "api_keys_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "200": { "description": "Created API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose API-key or browser-session authentication.\nSet a name or credit limit.\nReplace a key when credentials need rotation.\n\n\n
" }, "x-breeze-api-name": "Create an API key", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-create", "x-breeze-auth": "browser-session", "x-sdk-exclude": true } }, "/v1/api-keys/current": { "get": { "tags": [ "Account" ], "summary": "Get the current API key", "description": "Return the API key that authenticated this request, including its status and Key Budget counters. Use it to check whether a key is still usable before starting work. The budget is read fresh on every call, no credits are reserved, and an exhausted budget still returns 200 with credit_remaining at 0. Browser sessions are not accepted on this endpoint.", "operationId": "api_keys_current", "responses": { "200": { "description": "The authenticating API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentApiKeyResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose API-key or browser-session authentication.\nCheck the account credit balance.\nInspect account-level usage.\n\n\n
" }, "x-breeze-api-name": "Get the current API key", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-current", "x-breeze-errors": [ { "code": "AUTH_REQUIRED", "description": "The API key is missing, invalid, disabled, or expired, or the request used a browser session." } ], "x-breeze-response-examples": [ { "label": "200 OK (finite budget)", "tone": "success", "lang": "json", "code": "{\n \"api_key\": {\n \"id\": \"key_asa2whhpag\",\n \"name\": \"realtime\",\n \"prefix\": \"brz_Y3XI-NHN\",\n \"status\": \"active\",\n \"credit_limit\": 2000,\n \"credit_used\": 12.5,\n \"credit_reserved\": 0,\n \"credit_remaining\": 1987.5\n }\n}" }, { "label": "200 OK (no budget)", "tone": "success", "lang": "json", "code": "{\n \"api_key\": {\n \"id\": \"key_asa2whhpag\",\n \"name\": \"realtime\",\n \"prefix\": \"brz_Y3XI-NHN\",\n \"status\": \"active\",\n \"credit_limit\": null,\n \"credit_used\": 12.5,\n \"credit_reserved\": 0,\n \"credit_remaining\": null\n }\n}" } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/api-keys/current\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" } ] } }, "/v1/api-keys/{key_id}": { "delete": { "tags": [ "Account" ], "summary": "Delete an API key", "description": "Delete an API key. Historical usage records are retained.", "operationId": "api_keys_delete", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" }, "description": "Public API key identifier returned by GET /v1/api-keys." } ], "responses": { "204": { "description": "Key deleted successfully." }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nTemporarily disable a key instead.\nVerify which key you intend to delete.\nChoose API-key or browser-session authentication.\n\n\n
" }, "x-breeze-api-name": "Delete an API key", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-delete", "x-breeze-auth": "browser-session", "x-sdk-exclude": true }, "patch": { "tags": [ "Account" ], "summary": "Update an API key", "description": "Update an API key name and/or hard credit limit.", "operationId": "api_keys_update", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" }, "description": "Public API key identifier returned by GET /v1/api-keys." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyRequest" } } } }, "responses": { "200": { "description": "Updated API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nReview keys and their current configuration.\nReset a key budget counter.\nChoose API-key or browser-session authentication.\n\n\n
" }, "x-breeze-api-name": "Update an API key", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-update", "x-breeze-auth": "browser-session", "x-sdk-exclude": true } }, "/v1/api-keys/{key_id}/disable": { "post": { "tags": [ "Account" ], "summary": "Disable an API key", "description": "Disable an API key without deleting it.", "operationId": "api_keys_disable", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" }, "description": "Public API key identifier returned by GET /v1/api-keys." } ], "responses": { "200": { "description": "Updated API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nEnable the key again when needed.\nReplace the credential rather than reusing it.\nChoose API-key or browser-session authentication.\n\n\n
" }, "x-breeze-api-name": "Disable an API key", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-disable", "x-breeze-auth": "browser-session", "x-sdk-exclude": true } }, "/v1/api-keys/{key_id}/enable": { "post": { "tags": [ "Account" ], "summary": "Enable an API key", "description": "Re-enable a disabled API key.", "operationId": "api_keys_enable", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" }, "description": "Public API key identifier returned by GET /v1/api-keys." } ], "responses": { "200": { "description": "Updated API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nInspect key status and configuration.\nDisable the key to stop its use.\nChoose API-key or browser-session authentication.\n\n\n
" }, "x-breeze-api-name": "Enable an API key", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-enable", "x-breeze-auth": "browser-session", "x-sdk-exclude": true } }, "/v1/api-keys/{key_id}/rotate": { "post": { "tags": [ "Account" ], "summary": "Rotate an API key", "description": "Create a replacement API key and mark the source key as expiring. The replacement secret is returned once.", "operationId": "api_keys_rotate", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" }, "description": "Public API key identifier returned by GET /v1/api-keys." } ], "responses": { "200": { "description": "Replacement API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nChoose API-key or browser-session authentication.\nReview the replacement key.\nConfigure the replacement key budget.\n\n\n
" }, "x-breeze-api-name": "Rotate an API key", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-rotate", "x-breeze-auth": "browser-session", "x-sdk-exclude": true } }, "/v1/api-keys/{key_id}/credit-budget/reset": { "post": { "tags": [ "Account" ], "summary": "Reset an API key credit budget", "description": "Start a new budget epoch and reset Used and Reserved to zero. This does not add credits to the account balance.", "operationId": "api_keys_credit_budget_reset", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Key Id" }, "description": "Public API key identifier returned by GET /v1/api-keys." } ], "responses": { "200": { "description": "Reset API key budget.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nSet the key credit limit.\nReview key budgets and status.\nInspect account usage before changing budgets.\n\n\n
" }, "x-breeze-api-name": "Reset an API key credit budget", "x-breeze-docs-group": "Account", "x-breeze-docs-href": "/docs/api-reference/account/api-keys-credit-budget-reset", "x-breeze-auth": "browser-session", "x-sdk-exclude": true } }, "/v1/history": { "get": { "tags": [ "History" ], "summary": "List history items", "description": "List text-to-speech history items.", "operationId": "history_list", "parameters": [ { "name": "voice_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id" }, "description": "Filter by voice_id. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, { "name": "model_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model Id" }, "description": "Filter by model_id. See [List models](https://docs.breezeblue.ai/api-reference/models/list-models)." }, { "name": "search", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Search" }, "description": "Filter by script text." }, { "name": "sort_direction", "in": "query", "required": false, "schema": { "type": "string", "default": "desc", "title": "Sort Direction" }, "description": "Sort direction: asc or desc." }, { "name": "start_after_history_item_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start After History Item Id" }, "description": "Cursor for forward pagination." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "name": "status_class", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Class" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "description": "Page number for offset pagination." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Page Size" }, "description": "Records per page." } ], "responses": { "200": { "description": "Paginated history list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryListResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "400": { "description": "HTTP 400 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nInspect one generation result.\nDownload a completed generation.\nFind, download, and remove past generations.\n\n\n
" }, "x-breeze-api-name": "List history items", "x-breeze-docs-group": "History", "x-breeze-docs-href": "/docs/api-reference/history/list", "x-breeze-errors": [ { "code": "BAD_REQUEST", "description": "One of the filter values is not valid for this endpoint." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/history\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nitems = client.history.list()\nfor item in items[\"history\"]:\n print(item[\"history_item_id\"], item[\"text\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst items = await client.history.list();\nfor (const item of items.history) {\n console.log(item.historyItemId, item.text);\n}" } ] } }, "/v1/history/{history_item_id}": { "get": { "tags": [ "History" ], "summary": "Get a history item", "description": "Get a history item by ID.", "operationId": "history_get", "parameters": [ { "name": "history_item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "History Item Id" }, "description": "History item identifier returned by generation responses or GET /v1/history. See [Listing history](https://docs.breezeblue.ai/guides/managing-history#listing-recent-requests)." } ], "responses": { "200": { "description": "History item.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryItemResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nDownload the audio for this item.\nRemove an item you no longer need.\nFind, download, and remove past generations.\n\n\n
" }, "x-breeze-api-name": "Get a history item", "x-breeze-docs-group": "History", "x-breeze-docs-href": "/docs/api-reference/history/get", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The history_item_id does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/history/hist_01haudio\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nitem = client.history.get(\"hist_01haudio\")\n\nprint(item[\"history_item_id\"], item[\"text\"])" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst item = await client.history.get(\"hist_01haudio\");\n\nconsole.log(item.historyItemId, item.text);" } ] }, "delete": { "tags": [ "History" ], "summary": "Delete a history item", "description": "Soft-delete a history item.", "operationId": "history_delete", "parameters": [ { "name": "history_item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "History Item Id" }, "description": "History item identifier returned by generation responses or GET /v1/history. See [Listing history](https://docs.breezeblue.ai/guides/managing-history#listing-recent-requests)." } ], "responses": { "200": { "description": "Delete status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericStatusResponse" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nInspect the item before deleting it.\nDownload a copy before deletion.\nFind, download, and remove past generations.\n\n\n
" }, "x-breeze-api-name": "Delete a history item", "x-breeze-docs-group": "History", "x-breeze-docs-href": "/docs/api-reference/history/delete", "x-breeze-errors": [ { "code": "RESOURCE_NOT_FOUND", "description": "The history_item_id does not exist or is not accessible." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/history/hist_01haudio\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "import os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\nclient.history.delete(\"hist_01haudio\")" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nawait client.history.delete(\"hist_01haudio\");" } ] } }, "/v1/history/{history_item_id}/audio": { "get": { "tags": [ "History" ], "summary": "Download history audio", "description": "Download the audio for a completed history item.", "operationId": "history_audio_download", "parameters": [ { "name": "history_item_id", "in": "path", "required": true, "schema": { "type": "string", "title": "History Item Id" }, "description": "History item identifier returned by generation responses or GET /v1/history. See [Listing history](https://docs.breezeblue.ai/guides/managing-history#listing-recent-requests)." } ], "responses": { "200": { "description": "Binary audio download.", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } }, "audio/flac": { "schema": { "type": "string", "format": "binary" } }, "audio/aac": { "schema": { "type": "string", "format": "binary" } }, "audio/opus": { "schema": { "type": "string", "format": "binary" } }, "audio/pcm": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "content-disposition": { "description": "Suggested filename.", "schema": { "type": "string" } }, "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "425": { "description": "HTTP 425 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying the generation audio request.", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nRead the audio metadata and generation details.\nFind other generated audio.\nFind, download, and remove past generations.\n\n\n
" }, "x-breeze-api-name": "Download history audio", "x-breeze-docs-group": "History", "x-breeze-docs-href": "/docs/api-reference/history/audio", "x-breeze-errors": [ { "code": "GENERATION_NOT_READY", "description": "The history item is still running; retry after the Retry-After interval." }, { "code": "GENERATION_FAILED", "description": "The history item generation failed." }, { "code": "RESOURCE_NOT_FOUND", "description": "The history audio does not exist or is no longer available." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/history/hist_01haudio/audio\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python SDK", "source": "from pathlib import Path\n\nfrom breeze_blue import save\n\nimport os\n\nfrom breeze_blue import BreezeBlue\n\nclient = BreezeBlue(api_key=os.environ[\"BREEZE_API_KEY\"])\n\naudio = client.history.download_audio(\"hist_01haudio\")\nsave(audio, Path(\"history.mp3\"))" }, { "lang": "TypeScript", "label": "TypeScript SDK", "source": "import { save } from \"@breeze.blue/sdk/node\";\nimport { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient({\n apiKey: process.env.BREEZE_API_KEY!,\n});\n\nconst audio = await client.history.downloadAudio(\"hist_01haudio\");\nawait save(audio, \"history.mp3\");" } ] } }, "/v1/studio/projects": { "get": { "tags": [ "Studio" ], "summary": "List projects", "description": "List your Studio projects, most recently updated first.", "operationId": "studio_projects_list", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "default": "", "title": "Q" }, "description": "Case-insensitive match on project title." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "description": "Page number, starting at 1." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Page Size" }, "description": "Projects per page, up to 100." } ], "responses": { "200": { "description": "A page of projects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nRead a project's script and clip settings.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "List projects", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/projects-list", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.projects.list()" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.projects.list();" } ] }, "post": { "tags": [ "Studio" ], "summary": "Create a project", "description": "Create a project with one chapter and one empty clip. Requires a paid Studio subscription and a free saved-project slot. Retrying with the same operation_id and body returns the original project.", "operationId": "studio_projects_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreate" } } } }, "responses": { "200": { "description": "The created project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nRead a project's script and clip settings.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Create a project", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/projects-create", "x-breeze-errors": [ { "code": "BILLING_SUBSCRIPTION_REQUIRED", "description": "The account has no paid Studio subscription." }, { "code": "FORBIDDEN", "description": "All saved-project slots are in use." }, { "code": "CONFLICT", "description": "operation_id was used for a different or deleted project." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"title\": \"An evening story\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.projects.create({\n \"title\": \"An evening story\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.projects.create({\n title: \"An evening story\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n});" } ] } }, "/v1/studio/projects/import": { "post": { "tags": [ "Studio" ], "summary": "Import a project", "description": "Create a project from a complete script in one step: up to 20 chapters with up to 400 clips each. Every voice is checked before anything is created. client_refs in the response maps each client_ref to the created chapter or clip ID. Requires a paid Studio subscription and a free saved-project slot.", "operationId": "studio_projects_import", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectImport" } } }, "required": true }, "responses": { "200": { "description": "The imported project, with client_refs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "HTTP 403 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nRead a project's script and clip settings.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Import a project", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/projects-import", "x-breeze-errors": [ { "code": "BILLING_SUBSCRIPTION_REQUIRED", "description": "The account has no paid Studio subscription." }, { "code": "FORBIDDEN", "description": "All saved-project slots are in use." }, { "code": "RESOURCE_NOT_FOUND", "description": "A voice_id does not exist or is not available to the account." }, { "code": "CONFLICT", "description": "operation_id was used for a different or deleted project." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/import\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"title\": \"An evening story\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"chapters\": [\n {\n \"client_ref\": \"opening\",\n \"title\": \"Opening\",\n \"clips\": [\n {\n \"client_ref\": \"opening.line1\",\n \"script\": \"The lights came on.\"\n }\n ]\n }\n ]\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.projects.import_project({\n \"title\": \"An evening story\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"chapters\": [\n {\n \"client_ref\": \"opening\",\n \"title\": \"Opening\",\n \"clips\": [\n {\n \"client_ref\": \"opening.line1\",\n \"script\": \"The lights came on.\",\n },\n ],\n },\n ],\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.projects.importProject({\n title: \"An evening story\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n chapters: [{\n clientRef: \"opening\",\n title: \"Opening\",\n clips: [{\n clientRef: \"opening.line1\",\n script: \"The lights came on.\",\n }],\n }],\n});" } ] } }, "/v1/studio/projects/{project_id}": { "get": { "tags": [ "Studio" ], "summary": "Get a project", "description": "Get a project's settings, chapter and clip counts, and current edit_token.", "operationId": "studio_projects_get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nRead a project's script and clip settings.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Get a project", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/projects-get", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.projects.get(\"prj_example\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.projects.get(\"prj_example\");" } ] }, "patch": { "tags": [ "Studio" ], "summary": "Update a project", "description": "Update the title, description, TTS settings, or clip defaults. Omitted fields are unchanged; send default_voice_id as null to clear it. Changing default_silence_ms makes clips with an explicit 0 ms silence inherit the new default.", "operationId": "studio_projects_update", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPatch" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nRead a project's script and clip settings.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Update a project", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/projects-update", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"default_silence_ms\": 300\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.projects.update(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"default_silence_ms\": 300,\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.projects.update(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n defaultSilenceMs: 300,\n});" } ] }, "delete": { "tags": [ "Studio" ], "summary": "Delete a project", "description": "Delete a project and its clips. Audio files placed in the project are not deleted.", "operationId": "studio_projects_delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "Deletion result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nRead a project's script and clip settings.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Delete a project", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/projects-delete", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.projects.delete(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.projects.delete(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n});" } ] } }, "/v1/studio/projects/{project_id}/chapters": { "get": { "tags": [ "Studio" ], "summary": "List chapters", "description": "List chapters in project order, each with its clip IDs.", "operationId": "studio_chapters_list", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Deleted" }, "description": "Include deleted chapters, which can be restored." } ], "responses": { "200": { "description": "Chapters and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChapterList" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nMove clips between chapters.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "List chapters", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/chapters-list", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/chapters\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.chapters.list(\"prj_example\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.chapters.list(\"prj_example\");" } ] }, "post": { "tags": [ "Studio" ], "summary": "Create a chapter", "description": "Append an empty chapter to the project. Its ID is returned in created_ids.", "operationId": "studio_chapters_create", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChapterCreate" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nMove clips between chapters.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Create a chapter", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/chapters-create", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/chapters\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"title\": \"Opening\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.chapters.create(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"title\": \"Opening\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.chapters.create(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n title: \"Opening\",\n});" } ] } }, "/v1/studio/projects/{project_id}/chapters/reorder": { "patch": { "tags": [ "Studio" ], "summary": "Reorder chapters", "description": "Set the order of active chapters. ids must contain every active chapter exactly once.", "operationId": "studio_chapters_reorder", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reorder" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nMove clips between chapters.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Reorder chapters", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/chapters-reorder", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/chapters/reorder\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"ids\": [\n \"123e4567-e89b-42d3-a456-426614174002\",\n \"123e4567-e89b-42d3-a456-426614174005\"\n ]\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.chapters.reorder(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"ids\": [\n \"123e4567-e89b-42d3-a456-426614174002\",\n \"123e4567-e89b-42d3-a456-426614174005\",\n ],\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.chapters.reorder(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n ids: [\"123e4567-e89b-42d3-a456-426614174002\", \"123e4567-e89b-42d3-a456-426614174005\"],\n});" } ] } }, "/v1/studio/projects/{project_id}/chapters/{chapter_id}": { "get": { "tags": [ "Studio" ], "summary": "Get a chapter", "description": "Get one chapter, including a deleted one, with its clip IDs.", "operationId": "studio_chapters_get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "chapter_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Chapter Id" }, "description": "Chapter ID." } ], "responses": { "200": { "description": "The chapter and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChapterResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nMove clips between chapters.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Get a chapter", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/chapters-get", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/chapters/123e4567-e89b-42d3-a456-426614174002\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.chapters.get(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.chapters.get(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\");" } ] }, "patch": { "tags": [ "Studio" ], "summary": "Rename a chapter", "description": "Change a chapter's title.", "operationId": "studio_chapters_update", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "chapter_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Chapter Id" }, "description": "Chapter ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChapterPatch" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nMove clips between chapters.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Rename a chapter", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/chapters-update", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/chapters/123e4567-e89b-42d3-a456-426614174002\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"title\": \"Opening\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.chapters.update(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"title\": \"Opening\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.chapters.update(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n title: \"Opening\",\n});" } ] }, "delete": { "tags": [ "Studio" ], "summary": "Delete a chapter", "description": "Delete a chapter so it can be restored later. Set move_to_chapter_id to keep its clips by moving them to another chapter first; otherwise they stay in the deleted chapter. A project keeps at least one active chapter.", "operationId": "studio_chapters_delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "chapter_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Chapter Id" }, "description": "Chapter ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChapterDelete" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nMove clips between chapters.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Delete a chapter", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/chapters-delete", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/chapters/123e4567-e89b-42d3-a456-426614174002\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"move_to_chapter_id\": \"123e4567-e89b-42d3-a456-426614174005\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.chapters.delete(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"move_to_chapter_id\": \"123e4567-e89b-42d3-a456-426614174005\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.chapters.delete(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n moveToChapterId: \"123e4567-e89b-42d3-a456-426614174005\",\n});" } ] } }, "/v1/studio/projects/{project_id}/chapters/{chapter_id}/restore": { "post": { "tags": [ "Studio" ], "summary": "Restore a chapter", "description": "Restore a deleted chapter with the clips it still contains.", "operationId": "studio_chapters_restore", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "chapter_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Chapter Id" }, "description": "Chapter ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nMove clips between chapters.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Restore a chapter", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/chapters-restore", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/chapters/123e4567-e89b-42d3-a456-426614174002/restore\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.chapters.restore(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.chapters.restore(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174002\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n});" } ] } }, "/v1/studio/projects/{project_id}/clips": { "get": { "tags": [ "Studio" ], "summary": "List clips", "description": "List clips in chapter order with stored and effective settings.", "operationId": "studio_clips_list", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "chapter_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chapter Id" }, "description": "Only list clips in this chapter." }, { "name": "include_deleted", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "title": "Include Deleted" }, "description": "Include clips in deleted chapters." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1, "title": "Page" }, "description": "Page number, starting at 1." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 400, "minimum": 1, "default": 100, "title": "Page Size" }, "description": "Clips per page, up to 400." } ], "responses": { "200": { "description": "A page of clips and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipList" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "List clips", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-list", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.list(\"prj_example\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.list(\"prj_example\");" } ] }, "post": { "tags": [ "Studio" ], "summary": "Create a clip", "description": "Add a clip after after_clip_id, or at the end of the chapter. Without chapter_id, the clip goes to the first active chapter. Without voice_id, the clip uses the project's default voice. Its ID is returned in created_ids.", "operationId": "studio_clips_create", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipCreate" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Create a clip", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-create", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"script\": \"A new day begins.\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.create(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"script\": \"A new day begins.\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.create(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n script: \"A new day begins.\",\n});" } ] } }, "/v1/studio/projects/{project_id}/clips/batch": { "post": { "tags": [ "Studio" ], "summary": "Create clips in bulk", "description": "Add up to 400 clips to one chapter in a single atomic write. Placement follows Create a clip; created_ids lists the new IDs in input order.", "operationId": "studio_clips_batch_create", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipBatchCreate" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Create clips in bulk", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-batch-create", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/batch\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"clips\": [\n {\n \"script\": \"A new day begins.\"\n }\n ]\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.batch_create(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"clips\": [\n {\n \"script\": \"A new day begins.\",\n },\n ],\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.batchCreate(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n clips: [{\n script: \"A new day begins.\",\n }],\n});" } ] }, "patch": { "tags": [ "Studio" ], "summary": "Update clips in bulk", "description": "Update up to 100 clips in a single atomic write. Each item names a clip_id and the fields to change.", "operationId": "studio_clips_batch_update", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipBatchPatch" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nCheck stored and effective clip settings.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Update clips in bulk", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-batch-update", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/batch\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"updates\": [\n {\n \"instructions\": \"Speak softly.\",\n \"clip_id\": \"clp_example\"\n }\n ]\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.batch_update(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"updates\": [\n {\n \"instructions\": \"Speak softly.\",\n \"clip_id\": \"clp_example\",\n },\n ],\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.batchUpdate(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n updates: [{\n instructions: \"Speak softly.\",\n clipId: \"clp_example\",\n }],\n});" } ] } }, "/v1/studio/projects/{project_id}/clips/bulk-delete": { "post": { "tags": [ "Studio" ], "summary": "Delete clips in bulk", "description": "Delete up to 400 clips in a single atomic write. A project keeps at least one clip.", "operationId": "studio_clips_bulk_delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipBulkDelete" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Delete clips in bulk", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-bulk-delete", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/bulk-delete\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"clip_ids\": [\n \"clp_example\"\n ]\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.bulk_delete(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"clip_ids\": [\n \"clp_example\",\n ],\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.bulkDelete(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n clipIds: [\"clp_example\"],\n});" } ] } }, "/v1/studio/projects/{project_id}/clips/reorder": { "patch": { "tags": [ "Studio" ], "summary": "Reorder clips", "description": "Set the order of clips in one chapter. ids must contain every clip in the chapter exactly once.", "operationId": "studio_clips_reorder", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipReorder" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Reorder clips", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-reorder", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/reorder\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"ids\": [\n \"clp_example\",\n \"clp_example2\"\n ],\n \"chapter_id\": \"123e4567-e89b-42d3-a456-426614174002\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.reorder(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"ids\": [\n \"clp_example\",\n \"clp_example2\",\n ],\n \"chapter_id\": \"123e4567-e89b-42d3-a456-426614174002\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.reorder(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n ids: [\"clp_example\", \"clp_example2\"],\n chapterId: \"123e4567-e89b-42d3-a456-426614174002\",\n});" } ] } }, "/v1/studio/projects/{project_id}/clips/move": { "post": { "tags": [ "Studio" ], "summary": "Move clips", "description": "Move clips to another chapter, after after_clip_id or at the end. Audio that follows a moved clip on a chapter track moves with it.", "operationId": "studio_clips_move", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipMove" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Move clips", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-move", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/move\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"clip_ids\": [\n \"clp_example\"\n ],\n \"chapter_id\": \"123e4567-e89b-42d3-a456-426614174002\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.move(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"clip_ids\": [\n \"clp_example\",\n ],\n \"chapter_id\": \"123e4567-e89b-42d3-a456-426614174002\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.move(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n clipIds: [\"clp_example\"],\n chapterId: \"123e4567-e89b-42d3-a456-426614174002\",\n});" } ] } }, "/v1/studio/projects/{project_id}/clips/{clip_id}": { "get": { "tags": [ "Studio" ], "summary": "Get a clip", "description": "Get one clip with its script, voice, playback, and the instructions and silence it inherits from the project.", "operationId": "studio_clips_get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "clip_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Clip Id" }, "description": "Clip ID, such as clp_…." } ], "responses": { "200": { "description": "The clip and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Get a clip", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-get", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/clp_example\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.get(\"prj_example\", \"clp_example\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.get(\"prj_example\", \"clp_example\");" } ] }, "patch": { "tags": [ "Studio" ], "summary": "Update a clip", "description": "Change a clip's name, script, instructions, voice, playback, or trailing silence. Omitted fields are unchanged.", "operationId": "studio_clips_update", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "clip_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Clip Id" }, "description": "Clip ID, such as clp_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipPatch" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Update a clip", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-update", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/clp_example\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"script\": \"A new day begins.\",\n \"trailing_silence_ms\": null\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.update(\"prj_example\", \"clp_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"script\": \"A new day begins.\",\n \"trailing_silence_ms\": None,\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.update(\"prj_example\", \"clp_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n script: \"A new day begins.\",\n trailingSilenceMs: null,\n});" } ] }, "delete": { "tags": [ "Studio" ], "summary": "Delete a clip", "description": "Delete one clip. A project keeps at least one clip.", "operationId": "studio_clips_delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "clip_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Clip Id" }, "description": "Clip ID, such as clp_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nImport scripts, edit safely, and retry writes.\nChange up to 100 clips in one write.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Delete a clip", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/clips-delete", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/clips/clp_example\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.clips.delete(\"prj_example\", \"clp_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.clips.delete(\"prj_example\", \"clp_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n});" } ] } }, "/v1/studio/projects/{project_id}/tracks": { "get": { "tags": [ "Studio" ], "summary": "List tracks", "description": "List the read-only narration track followed by audio tracks and their instances.", "operationId": "studio_tracks_list", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "responses": { "200": { "description": "Tracks and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackList" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace audio on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "List tracks", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/tracks-list", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.tracks.list(\"prj_example\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.tracks.list(\"prj_example\");" } ] }, "post": { "tags": [ "Studio" ], "summary": "Create a track", "description": "Add an audio track for music or sound effects. Set chapter_id to limit it to one chapter. Its ID is returned in created_ids.", "operationId": "studio_tracks_create", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackCreate" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace audio on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Create a track", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/tracks-create", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"name\": \"Background music\",\n \"volume\": 0.3\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.tracks.create(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"name\": \"Background music\",\n \"volume\": 0.3,\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.tracks.create(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n name: \"Background music\",\n volume: 0.3,\n});" } ] } }, "/v1/studio/projects/{project_id}/tracks/reorder": { "patch": { "tags": [ "Studio" ], "summary": "Reorder tracks", "description": "Set the order of audio tracks. ids must contain every audio track exactly once; narration is not included.", "operationId": "studio_tracks_reorder", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reorder" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace audio on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Reorder tracks", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/tracks-reorder", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/reorder\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"ids\": [\n \"123e4567-e89b-42d3-a456-426614174002\",\n \"123e4567-e89b-42d3-a456-426614174005\"\n ]\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.tracks.reorder(\"prj_example\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"ids\": [\n \"123e4567-e89b-42d3-a456-426614174002\",\n \"123e4567-e89b-42d3-a456-426614174005\",\n ],\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.tracks.reorder(\"prj_example\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n ids: [\"123e4567-e89b-42d3-a456-426614174002\", \"123e4567-e89b-42d3-a456-426614174005\"],\n});" } ] } }, "/v1/studio/projects/{project_id}/tracks/{track_id}": { "get": { "tags": [ "Studio" ], "summary": "Get a track", "description": "Get one track and its instances. Use narration as track_id for the narration track.", "operationId": "studio_tracks_get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." } ], "responses": { "200": { "description": "The track and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace audio on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Get a track", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/tracks-get", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.tracks.get(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.tracks.get(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\");" } ] }, "patch": { "tags": [ "Studio" ], "summary": "Update a track", "description": "Change an audio track's name, chapter scope, volume, or mute state. The narration track is read-only.", "operationId": "studio_tracks_update", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackPatch" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace audio on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Update a track", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/tracks-update", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"muted\": true\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.tracks.update(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"muted\": True,\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.tracks.update(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n muted: true,\n});" } ] }, "delete": { "tags": [ "Studio" ], "summary": "Delete a track", "description": "Delete an audio track and its instances. The audio files are not deleted.", "operationId": "studio_tracks_delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace audio on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Delete a track", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/tracks-delete", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.tracks.delete(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.tracks.delete(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n});" } ] } }, "/v1/studio/projects/{project_id}/tracks/{track_id}/instances": { "get": { "tags": [ "Studio" ], "summary": "List instances", "description": "List the audio instances on a track.", "operationId": "studio_instances_list", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." } ], "responses": { "200": { "description": "Instances and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceList" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nCheck that audio is ready to place.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "List instances", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/instances-list", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003/instances\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.instances.list(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.instances.list(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\");" } ] }, "post": { "tags": [ "Studio" ], "summary": "Create an instance", "description": "Place a ready audio file on a track. A fixed position starts at a frame; a follow position starts at the start or end of a clip. Instances on one track cannot overlap. Its ID is returned in created_ids.", "operationId": "studio_instances_create", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceCreate" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nCheck that audio is ready to place.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Create an instance", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/instances-create", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003/instances\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"file_id\": \"123e4567-e89b-42d3-a456-426614174001\",\n \"position\": {\n \"mode\": \"fixed\",\n \"frame\": 0\n },\n \"trim_end\": 480000\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.instances.create(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"file_id\": \"123e4567-e89b-42d3-a456-426614174001\",\n \"position\": {\n \"mode\": \"fixed\",\n \"frame\": 0,\n },\n \"trim_end\": 480000,\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.instances.create(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n fileId: \"123e4567-e89b-42d3-a456-426614174001\",\n position: {\n mode: \"fixed\",\n frame: 0,\n },\n trimEnd: 480000,\n});" } ] } }, "/v1/studio/projects/{project_id}/tracks/{track_id}/instances/{instance_id}": { "get": { "tags": [ "Studio" ], "summary": "Get an instance", "description": "Get one audio instance. issues contains anchor_missing when its followed clip is gone.", "operationId": "studio_instances_get", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." }, { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Instance Id" }, "description": "Audio instance ID." } ], "responses": { "200": { "description": "The instance and the current edit_token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nCheck that audio is ready to place.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Get an instance", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/instances-get", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003/instances/123e4567-e89b-42d3-a456-426614174004\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.instances.get(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", \"123e4567-e89b-42d3-a456-426614174004\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.instances.get(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", \"123e4567-e89b-42d3-a456-426614174004\");" } ] }, "patch": { "tags": [ "Studio" ], "summary": "Update an instance", "description": "Change an instance's file, position, trim, length, or effects, or move it to another audio track with track_id. position and effects are merged into the current values.", "operationId": "studio_instances_update", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." }, { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Instance Id" }, "description": "Audio instance ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstancePatch" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nCheck that audio is ready to place.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Update an instance", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/instances-update", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003/instances/123e4567-e89b-42d3-a456-426614174004\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"position\": {\n \"mode\": \"follow\",\n \"clip_id\": \"clp_example\",\n \"edge\": \"start\"\n }\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.instances.update(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", \"123e4567-e89b-42d3-a456-426614174004\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"position\": {\n \"mode\": \"follow\",\n \"clip_id\": \"clp_example\",\n \"edge\": \"start\",\n },\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.instances.update(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", \"123e4567-e89b-42d3-a456-426614174004\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n position: {\n mode: \"follow\",\n clipId: \"clp_example\",\n edge: \"start\",\n },\n});" } ] }, "delete": { "tags": [ "Studio" ], "summary": "Delete an instance", "description": "Remove an audio instance from its track. The audio file is not deleted.", "operationId": "studio_instances_delete", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Project Id" }, "description": "Studio project ID, such as prj_…." }, { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Track Id" }, "description": "Audio track ID, or narration for the narration track." }, { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Instance Id" }, "description": "Audio instance ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Edit" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nCheck that audio is ready to place.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Delete an instance", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/instances-delete", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_edit_token is stale, or operation_id was reused with a different body. meta.latest_edit_token carries the current token for a stale project." }, { "code": "RESOURCE_NOT_FOUND", "description": "The project, chapter, clip, track, instance, or voice does not exist." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/studio/projects/prj_example/tracks/123e4567-e89b-42d3-a456-426614174003/instances/123e4567-e89b-42d3-a456-426614174004\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.instances.delete(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", \"123e4567-e89b-42d3-a456-426614174004\", {\n \"expected_edit_token\": \"replace_with_current_edit_token\",\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.instances.delete(\"prj_example\", \"123e4567-e89b-42d3-a456-426614174003\", \"123e4567-e89b-42d3-a456-426614174004\", {\n expectedEditToken: \"replace_with_current_edit_token\",\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n});" } ] } }, "/v1/studio/files": { "get": { "tags": [ "Studio" ], "summary": "List files", "description": "List audio files by name. Without project_id, only personal files not scoped to a project are listed.", "operationId": "studio_files_list", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id" }, "description": "List files scoped to this project." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "default": "", "title": "Q" }, "description": "Case-insensitive match on file name." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 0, "default": 0, "title": "Offset" }, "description": "Number of files to skip. Use next_offset from the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 100, "title": "Limit" }, "description": "Files per page, up to 500." } ], "responses": { "200": { "description": "A page of files.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileList" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "List files", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-list", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/files\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.list()" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.list();" } ] }, "post": { "tags": [ "Studio" ], "summary": "Create a file", "description": "Register an MP3 or WAV file of up to 1.5 GB before uploading it. Next, get an upload URL, upload the bytes, and complete the upload. Retrying with the same operation_id and body returns the same file.", "operationId": "studio_files_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileCreate" } } } }, "responses": { "200": { "description": "The created file, with status uploading.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileView" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Create a file", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-create", "x-breeze-errors": [ { "code": "STUDIO_FILE_NAME_TAKEN", "description": "A file with this name already exists in the same place." }, { "code": "CONFLICT", "description": "operation_id was used for a different or deleted file (meta.reason operation_reused)." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/files\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"project_id\": \"prj_example\",\n \"name\": \"background.mp3\",\n \"size_bytes\": 5242880,\n \"mime_type\": \"audio/mpeg\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.create({\n \"operation_id\": \"123e4567-e89b-42d3-a456-426614174000\",\n \"project_id\": \"prj_example\",\n \"name\": \"background.mp3\",\n \"size_bytes\": 5242880,\n \"mime_type\": \"audio/mpeg\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.create({\n operationId: \"123e4567-e89b-42d3-a456-426614174000\",\n projectId: \"prj_example\",\n name: \"background.mp3\",\n sizeBytes: 5242880,\n mimeType: \"audio/mpeg\",\n});" } ] } }, "/v1/studio/files/{file_id}": { "get": { "tags": [ "Studio" ], "summary": "Get a file", "description": "Get a file's processing status, length in frames, and failure details. status moves from uploading to queued and running, then to ready or failed.", "operationId": "studio_files_get", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" }, "description": "Audio file ID." } ], "responses": { "200": { "description": "The file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileView" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Get a file", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-get", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request GET \\\n --url \"https://api.breeze.blue/v1/studio/files/123e4567-e89b-42d3-a456-426614174001\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.get(\"123e4567-e89b-42d3-a456-426614174001\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.get(\"123e4567-e89b-42d3-a456-426614174001\");" } ] }, "patch": { "tags": [ "Studio" ], "summary": "Rename a file", "description": "Change a file's name.", "operationId": "studio_files_update", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" }, "description": "Audio file ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilePatch" } } } }, "responses": { "200": { "description": "The updated file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileView" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Rename a file", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-update", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_revision is stale; meta.latest_revision carries the current revision." }, { "code": "STUDIO_FILE_NAME_TAKEN", "description": "A file with this name already exists in the same place." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request PATCH \\\n --url \"https://api.breeze.blue/v1/studio/files/123e4567-e89b-42d3-a456-426614174001\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_revision\": 1,\n \"name\": \"rain.mp3\"\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.update(\"123e4567-e89b-42d3-a456-426614174001\", {\n \"expected_revision\": 1,\n \"name\": \"rain.mp3\",\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.update(\"123e4567-e89b-42d3-a456-426614174001\", {\n expectedRevision: 1,\n name: \"rain.mp3\",\n});" } ] }, "delete": { "tags": [ "Studio" ], "summary": "Delete a file", "description": "Delete an audio file. Remove every instance that uses it first.", "operationId": "studio_files_delete", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" }, "description": "Audio file ID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileDelete" } } } }, "responses": { "200": { "description": "Deletion result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Delete a file", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-delete", "x-breeze-errors": [ { "code": "CONFLICT", "description": "expected_revision is stale (meta.reason revision_mismatch), or instances still use the file (meta.reason in_use, with meta.references)." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request DELETE \\\n --url \"https://api.breeze.blue/v1/studio/files/123e4567-e89b-42d3-a456-426614174001\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\n \"expected_revision\": 1\n}'" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.delete(\"123e4567-e89b-42d3-a456-426614174001\", {\n \"expected_revision\": 1,\n})" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.delete(\"123e4567-e89b-42d3-a456-426614174001\", {\n expectedRevision: 1,\n});" } ] } }, "/v1/studio/files/{file_id}/upload": { "post": { "tags": [ "Studio" ], "summary": "Get an upload URL", "description": "Get a presigned URL for the file bytes. Send a PUT request to upload_url with the returned headers and without your API key. The URL expires after expires_in seconds; request a new one if it expires.", "operationId": "studio_files_upload_url", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" }, "description": "Audio file ID." } ], "responses": { "200": { "description": "The upload URL and required headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadResult" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "HTTP 409 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Get an upload URL", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-upload-url", "x-breeze-errors": [ { "code": "CONFLICT", "description": "The file is no longer waiting for an upload; meta.status carries its current status." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/files/123e4567-e89b-42d3-a456-426614174001/upload\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.upload_url(\"123e4567-e89b-42d3-a456-426614174001\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.uploadUrl(\"123e4567-e89b-42d3-a456-426614174001\");" } ] } }, "/v1/studio/files/{file_id}/complete": { "post": { "tags": [ "Studio" ], "summary": "Complete an upload", "description": "Confirm the upload and queue the file for processing. Poll Get a file until status is ready.", "operationId": "studio_files_complete", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" }, "description": "Audio file ID." } ], "responses": { "200": { "description": "The file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileView" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "503": { "description": "HTTP 503 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "HTTP 504 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Complete an upload", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-complete", "x-breeze-errors": [ { "code": "VALIDATION_ERROR", "description": "The uploaded size does not match size_bytes." }, { "code": "STUDIO_AUDIO_PROCESSING_FAILED", "description": "The upload is incomplete. Upload again, then retry." } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/files/123e4567-e89b-42d3-a456-426614174001/complete\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.complete(\"123e4567-e89b-42d3-a456-426614174001\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.complete(\"123e4567-e89b-42d3-a456-426614174001\");" } ] } }, "/v1/studio/files/{file_id}/retry": { "post": { "tags": [ "Studio" ], "summary": "Retry file processing", "description": "Queue a file whose processing failed for another attempt.", "operationId": "studio_files_retry", "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" }, "description": "Audio file ID." } ], "responses": { "200": { "description": "The file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileView" } } }, "headers": { "x-breeze-api-key-id": { "description": "Public API key identifier used to authenticate the request, when an API key was used.", "schema": { "type": "string" } } } }, "401": { "description": "HTTP 401 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "HTTP 404 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "HTTP 422 error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "x-mint": { "content": "
\n\n## Continue building\n\n\nUpload files and place them on tracks.\nPlace a ready file on a track.\nRun the same operations from a terminal.\n\n\n
" }, "x-breeze-api-name": "Retry file processing", "x-breeze-docs-group": "Studio", "x-breeze-docs-href": "/docs/api-reference/studio/files-retry", "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl \\\n --request POST \\\n --url \"https://api.breeze.blue/v1/studio/files/123e4567-e89b-42d3-a456-426614174001/retry\" \\\n --header \"xi-api-key: $BREEZE_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "from breeze_blue import BreezeBlue\n\nclient = BreezeBlue()\nresult = client.studio.files.retry(\"123e4567-e89b-42d3-a456-426614174001\")" }, { "lang": "TypeScript", "label": "TypeScript", "source": "import { BreezeBlueClient } from \"@breeze.blue/sdk\";\n\nconst client = new BreezeBlueClient();\nconst result = await client.studio.files.retry(\"123e4567-e89b-42d3-a456-426614174001\");" } ] } } }, "components": { "schemas": { "ChapterCreate": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title", "description": "Chapter title." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "title" ], "title": "ChapterCreate" }, "ChapterDelete": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "move_to_chapter_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Move To Chapter Id", "description": "Move the chapter's clips to this active chapter before deleting." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id" ], "title": "ChapterDelete" }, "ChapterList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ChapterView" }, "type": "array", "title": "Items", "description": "Resources in order." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." } }, "additionalProperties": false, "type": "object", "required": [ "items", "edit_token" ], "title": "ChapterList" }, "ChapterPatch": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title", "description": "New chapter title." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "title" ], "title": "ChapterPatch" }, "ChapterResult": { "properties": { "chapter": { "$ref": "#/components/schemas/ChapterView", "description": "The chapter." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." } }, "additionalProperties": false, "type": "object", "required": [ "chapter", "edit_token" ], "title": "ChapterResult" }, "ChapterView": { "properties": { "id": { "type": "string", "title": "Id", "description": "Chapter ID." }, "title": { "type": "string", "title": "Title", "description": "Chapter title." }, "deleted": { "type": "boolean", "title": "Deleted", "description": "Whether the chapter is deleted." }, "clip_ids": { "items": { "type": "string" }, "type": "array", "title": "Clip Ids", "description": "Clip IDs in order." } }, "additionalProperties": false, "type": "object", "required": [ "id", "title", "deleted", "clip_ids" ], "title": "ChapterView" }, "ClipBatchCreate": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "chapter_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Chapter Id", "description": "Target chapter. Defaults to the first active chapter." }, "after_clip_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "After Clip Id", "description": "Insert after this clip in the target chapter. Omit to append." }, "clips": { "items": { "$ref": "#/components/schemas/ClipFields" }, "type": "array", "maxItems": 400, "minItems": 1, "title": "Clips", "description": "Clips in order, from 1 to 400." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "clips" ], "title": "ClipBatchCreate" }, "ClipBatchPatch": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "updates": { "items": { "$ref": "#/components/schemas/ClipUpdateItem" }, "type": "array", "maxItems": 100, "minItems": 1, "title": "Updates", "description": "Clip changes, from 1 to 100." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "updates" ], "title": "ClipBatchPatch" }, "ClipBulkDelete": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "clip_ids": { "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, "type": "array", "maxItems": 400, "minItems": 1, "title": "Clip Ids", "description": "Clips to delete, from 1 to 400." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "clip_ids" ], "title": "ClipBulkDelete" }, "ClipCreate": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "client_ref": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Client Ref", "description": "Your label for this chapter or clip, unique within an import. Import maps it to the created ID in client_refs." }, "name": { "type": "string", "maxLength": 120, "title": "Name", "default": "", "description": "Clip label shown in the editor." }, "script": { "type": "string", "maxLength": 1000, "title": "Script", "default": "", "description": "Text to speak. Line breaks inside the text become spaces." }, "instructions": { "type": "string", "maxLength": 1000, "title": "Instructions", "default": "", "description": "Delivery instructions for this clip. Empty uses the project's default_instructions. See [Expressive controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls), [Voice instruction prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting)." }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Voice Id", "description": "Voice for this clip. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, "playback": { "$ref": "#/components/schemas/Playback", "description": "Playback speed and volume." }, "trailing_silence_ms": { "anyOf": [ { "type": "integer", "maximum": 600000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Trailing Silence Ms", "description": "Silence after the clip in milliseconds. null uses the project's default_silence_ms; 0 means no pause." }, "chapter_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Chapter Id", "description": "Target chapter. Defaults to the first active chapter." }, "after_clip_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "After Clip Id", "description": "Insert after this clip in the target chapter. Omit to append." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id" ], "title": "ClipCreate" }, "ClipFields": { "properties": { "client_ref": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Client Ref", "description": "Your label for this chapter or clip, unique within an import. Import maps it to the created ID in client_refs." }, "name": { "type": "string", "maxLength": 120, "title": "Name", "default": "", "description": "Clip label shown in the editor." }, "script": { "type": "string", "maxLength": 1000, "title": "Script", "default": "", "description": "Text to speak. Line breaks inside the text become spaces." }, "instructions": { "type": "string", "maxLength": 1000, "title": "Instructions", "default": "", "description": "Delivery instructions for this clip. Empty uses the project's default_instructions. See [Expressive controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls), [Voice instruction prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting)." }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Voice Id", "description": "Voice for this clip. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, "playback": { "$ref": "#/components/schemas/Playback", "description": "Playback speed and volume." }, "trailing_silence_ms": { "anyOf": [ { "type": "integer", "maximum": 600000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Trailing Silence Ms", "description": "Silence after the clip in milliseconds. null uses the project's default_silence_ms; 0 means no pause." } }, "additionalProperties": false, "type": "object", "title": "ClipFields" }, "ClipList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ClipView" }, "type": "array", "title": "Items", "description": "Resources in order." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." }, "total": { "type": "integer", "title": "Total", "description": "Total number of matching items." }, "page": { "type": "integer", "title": "Page", "description": "Current page number." }, "page_size": { "type": "integer", "title": "Page Size", "description": "Items per page." } }, "additionalProperties": false, "type": "object", "required": [ "items", "edit_token", "total", "page", "page_size" ], "title": "ClipList" }, "ClipMove": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "clip_ids": { "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, "type": "array", "maxItems": 400, "minItems": 1, "title": "Clip Ids", "description": "Clips to move, in the order they should appear." }, "chapter_id": { "type": "string", "format": "uuid", "title": "Chapter Id", "description": "Destination chapter." }, "after_clip_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "After Clip Id", "description": "Insert after this clip in the destination chapter. Omit to append." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "clip_ids", "chapter_id" ], "title": "ClipMove" }, "ClipPatch": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "name": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Name", "description": "Clip label shown in the editor." }, "script": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Script", "description": "Text to speak. Line breaks inside the text become spaces." }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Instructions", "description": "Delivery instructions for this clip. Empty uses the project's default_instructions. See [Expressive controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls), [Voice instruction prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting)." }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Voice Id", "description": "Voice for this clip. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, "playback": { "anyOf": [ { "$ref": "#/components/schemas/Playback" }, { "type": "null" } ], "description": "Playback speed and volume." }, "trailing_silence_ms": { "anyOf": [ { "type": "integer", "maximum": 600000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Trailing Silence Ms", "description": "Silence after the clip in milliseconds. null uses the project's default_silence_ms; 0 means no pause." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id" ], "title": "ClipPatch" }, "ClipReorder": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "ids": { "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, "type": "array", "maxItems": 10000, "minItems": 1, "title": "Ids", "description": "Every ID in the new order, each exactly once." }, "chapter_id": { "type": "string", "format": "uuid", "title": "Chapter Id", "description": "Chapter whose clips are reordered." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "ids", "chapter_id" ], "title": "ClipReorder" }, "ClipResult": { "properties": { "clip": { "$ref": "#/components/schemas/ClipView", "description": "The clip." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." } }, "additionalProperties": false, "type": "object", "required": [ "clip", "edit_token" ], "title": "ClipResult" }, "ClipUpdateItem": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Name", "description": "Clip label shown in the editor." }, "script": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Script", "description": "Text to speak. Line breaks inside the text become spaces." }, "instructions": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Instructions", "description": "Delivery instructions for this clip. Empty uses the project's default_instructions. See [Expressive controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls), [Voice instruction prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting)." }, "voice_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Voice Id", "description": "Voice for this clip. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, "playback": { "anyOf": [ { "$ref": "#/components/schemas/Playback" }, { "type": "null" } ], "description": "Playback speed and volume." }, "trailing_silence_ms": { "anyOf": [ { "type": "integer", "maximum": 600000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Trailing Silence Ms", "description": "Silence after the clip in milliseconds. null uses the project's default_silence_ms; 0 means no pause." }, "clip_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S", "title": "Clip Id", "description": "Clip to update. Each clip may appear once." } }, "additionalProperties": false, "type": "object", "required": [ "clip_id" ], "title": "ClipUpdateItem" }, "ClipView": { "properties": { "id": { "type": "string", "title": "Id", "description": "Clip ID." }, "chapter_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chapter Id", "description": "Chapter containing the clip." }, "name": { "type": "string", "title": "Name", "description": "Clip label." }, "script": { "type": "string", "title": "Script", "description": "Text to speak." }, "instructions": { "type": "string", "title": "Instructions", "description": "Instructions stored on the clip." }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Voice Id", "description": "Voice ID stored on the clip." }, "voice": { "anyOf": [ { "$ref": "#/components/schemas/VoiceSummary" }, { "type": "null" } ], "description": "Voice name and availability." }, "playback": { "$ref": "#/components/schemas/PlaybackView", "description": "Playback speed and volume." }, "trailing_silence_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Trailing Silence Ms", "description": "Silence stored on the clip; null inherits the project default." }, "effective_instructions": { "type": "string", "title": "Effective Instructions", "description": "Instructions used for generation after project defaults." }, "effective_trailing_silence_ms": { "type": "integer", "title": "Effective Trailing Silence Ms", "description": "Silence applied after the clip, in milliseconds." }, "version": { "type": "integer", "title": "Version", "description": "Clip version. Increases with each change." } }, "additionalProperties": false, "type": "object", "required": [ "id", "chapter_id", "name", "script", "instructions", "voice_id", "voice", "playback", "trailing_silence_ms", "effective_instructions", "effective_trailing_silence_ms", "version" ], "title": "ClipView" }, "CreateApiKeyRequest": { "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Name", "description": "Display name for the API key." }, "credit_limit": { "anyOf": [ { "type": "number", "maximum": 1000000000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Credit Limit", "description": "Hard credit limit for this API key, or null for Unlimited. See [Credit budgets](https://docs.breezeblue.ai/authentication#credit-budgets)." } }, "additionalProperties": false, "type": "object", "required": [ "name" ], "title": "CreateApiKeyRequest" }, "Deleted": { "properties": { "deleted": { "type": "boolean", "title": "Deleted", "default": true, "description": "true when the resource was deleted." }, "edit_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Edit Token", "description": "Always null for deleted projects and files." } }, "additionalProperties": false, "type": "object", "title": "Deleted" }, "Edit": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id" ], "title": "Edit" }, "Effects": { "properties": { "speed": { "type": "number", "maximum": 2.0, "minimum": 0.5, "title": "Speed", "default": 1, "description": "Playback speed, from 0.5 to 2." }, "volume": { "type": "number", "maximum": 2.0, "minimum": 0.0, "title": "Volume", "default": 1, "description": "Volume multiplier, from 0 to 2." }, "fade_in_seconds": { "type": "number", "maximum": 7200.0, "minimum": 0.0, "title": "Fade In Seconds", "default": 0, "description": "Fade-in duration in seconds." }, "fade_out_seconds": { "type": "number", "maximum": 7200.0, "minimum": 0.0, "title": "Fade Out Seconds", "default": 0, "description": "Fade-out duration in seconds." } }, "additionalProperties": false, "type": "object", "title": "Effects" }, "FileCreate": { "properties": { "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "project_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Project Id", "description": "Project that owns the file. Omit for a personal file." }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "File name, without path separators." }, "size_bytes": { "type": "integer", "maximum": 1610612736.0, "minimum": 1.0, "title": "Size Bytes", "description": "Exact upload size in bytes, up to 1.5 GB." }, "mime_type": { "type": "string", "enum": [ "audio/mpeg", "audio/wav" ], "title": "Mime Type", "description": "audio/mpeg for MP3 or audio/wav for WAV." } }, "additionalProperties": false, "type": "object", "required": [ "operation_id", "name", "size_bytes", "mime_type" ], "title": "FileCreate" }, "FileDelete": { "properties": { "expected_revision": { "type": "integer", "minimum": 1.0, "title": "Expected Revision", "description": "The file's current revision. A stale revision returns 409." } }, "additionalProperties": false, "type": "object", "required": [ "expected_revision" ], "title": "FileDelete" }, "FileList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/FileView" }, "type": "array", "title": "Items", "description": "Files sorted by name." }, "next_offset": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Next Offset", "description": "offset for the next page; null on the last page." } }, "additionalProperties": false, "type": "object", "required": [ "items", "next_offset" ], "title": "FileList" }, "FilePatch": { "properties": { "expected_revision": { "type": "integer", "minimum": 1.0, "title": "Expected Revision", "description": "The file's current revision. A stale revision returns 409." }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "New file name." } }, "additionalProperties": false, "type": "object", "required": [ "expected_revision", "name" ], "title": "FilePatch" }, "FileView": { "properties": { "id": { "type": "string", "title": "Id", "description": "File ID." }, "project_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Project Id", "description": "Project that owns the file; null for a personal file." }, "name": { "type": "string", "title": "Name", "description": "File name." }, "revision": { "type": "integer", "title": "Revision", "description": "Current revision. Send it as expected_revision to rename or delete." }, "status": { "type": "string", "enum": [ "uploading", "queued", "running", "ready", "failed" ], "title": "Status", "description": "uploading until the upload is completed, then queued and running while processing, and finally ready or failed." }, "frames": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Frames", "description": "Length in frames at sample_rate, once processed." }, "sample_rate": { "type": "integer", "title": "Sample Rate", "description": "Frame rate used for all Studio timing: 48000." }, "size_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Size Bytes", "description": "Original upload size in bytes." }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Code", "description": "Error code when processing failed." }, "error_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Reason", "description": "Machine-readable failure reason." }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Error Message", "description": "Readable failure message." }, "references": { "type": "integer", "title": "References", "description": "Number of instances that use the file." } }, "additionalProperties": false, "type": "object", "required": [ "id", "project_id", "name", "revision", "status", "frames", "sample_rate", "size_bytes", "error_code", "error_reason", "error_message", "references" ], "title": "FileView" }, "ImportChapter": { "properties": { "client_ref": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Client Ref", "description": "Your label for this chapter or clip, unique within an import. Import maps it to the created ID in client_refs." }, "title": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Title", "description": "Chapter title." }, "clips": { "items": { "$ref": "#/components/schemas/ClipFields" }, "type": "array", "maxItems": 400, "minItems": 1, "title": "Clips", "description": "Clips in order, from 1 to 400." } }, "additionalProperties": false, "type": "object", "required": [ "title", "clips" ], "title": "ImportChapter" }, "InstanceCreate": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "file_id": { "type": "string", "format": "uuid", "title": "File Id", "description": "Ready audio file to play." }, "position": { "$ref": "#/components/schemas/Position", "description": "Where the instance starts on the timeline." }, "trim_start": { "type": "integer", "maximum": 1036800000.0, "minimum": 0.0, "title": "Trim Start", "default": 0, "description": "First source frame to play." }, "trim_end": { "type": "integer", "maximum": 1036800000.0, "minimum": 1.0, "title": "Trim End", "description": "Source frame where playback stops. Must be greater than trim_start." }, "effects": { "$ref": "#/components/schemas/Effects", "description": "Volume, speed, and fades." }, "length": { "anyOf": [ { "type": "integer", "maximum": 1036800000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Length", "description": "Timeline length in frames. When longer than the trimmed audio, the audio repeats. null plays the trimmed audio once." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "file_id", "trim_end" ], "title": "InstanceCreate" }, "InstanceList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/InstanceView" }, "type": "array", "title": "Items", "description": "Resources in order." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." } }, "additionalProperties": false, "type": "object", "required": [ "items", "edit_token" ], "title": "InstanceList" }, "InstancePatch": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "file_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "File Id", "description": "Ready audio file to play." }, "position": { "anyOf": [ { "$ref": "#/components/schemas/Position" }, { "type": "null" } ], "description": "Position fields to change. Omitted fields keep their values." }, "trim_start": { "anyOf": [ { "type": "integer", "maximum": 1036800000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Trim Start", "description": "First source frame to play." }, "trim_end": { "anyOf": [ { "type": "integer", "maximum": 1036800000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Trim End", "description": "Source frame where playback stops. Must be greater than trim_start." }, "effects": { "anyOf": [ { "$ref": "#/components/schemas/Effects" }, { "type": "null" } ], "description": "Effect fields to change. Omitted fields keep their values." }, "length": { "anyOf": [ { "type": "integer", "maximum": 1036800000.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Length", "description": "Timeline length in frames. When longer than the trimmed audio, the audio repeats. null plays the trimmed audio once." }, "track_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Track Id", "description": "Move the instance to this audio track." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id" ], "title": "InstancePatch" }, "InstanceResult": { "properties": { "instance": { "$ref": "#/components/schemas/InstanceView", "description": "The instance." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." } }, "additionalProperties": false, "type": "object", "required": [ "instance", "edit_token" ], "title": "InstanceResult" }, "InstanceView": { "properties": { "id": { "type": "string", "title": "Id", "description": "Instance ID." }, "file_id": { "type": "string", "title": "File Id", "description": "Audio file played by the instance." }, "position": { "$ref": "#/components/schemas/Position", "description": "Where the instance starts on the timeline." }, "trim_start": { "type": "integer", "title": "Trim Start", "description": "First source frame to play." }, "trim_end": { "type": "integer", "title": "Trim End", "description": "Source frame where playback stops. Must be greater than trim_start." }, "effects": { "$ref": "#/components/schemas/Effects", "description": "Volume, speed, and fades." }, "length": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Length", "description": "Timeline length in frames. When longer than the trimmed audio, the audio repeats. null plays the trimmed audio once." }, "phase": { "type": "integer", "title": "Phase", "default": 0, "description": "Frame within the trimmed audio where a split repeated region resumes." }, "envelope_offset": { "type": "integer", "title": "Envelope Offset", "default": 0, "description": "Offset within the fade envelope shared by the parts of a split instance." }, "envelope_length": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Envelope Length", "description": "Length of the shared fade envelope; null uses the instance length." }, "issues": { "items": { "type": "string" }, "type": "array", "title": "Issues", "description": "Placement problems, such as anchor_missing when the followed clip is gone." } }, "additionalProperties": false, "type": "object", "required": [ "id", "file_id", "position", "trim_start", "trim_end", "effects" ], "title": "InstanceView" }, "Playback": { "properties": { "speed": { "type": "number", "maximum": 2.0, "minimum": 0.5, "title": "Speed", "default": 1, "description": "Playback speed, from 0.5 to 2." }, "volume": { "type": "number", "maximum": 2.0, "minimum": 0.01, "title": "Volume", "default": 1, "description": "Volume multiplier, from 0.01 to 2." } }, "additionalProperties": false, "type": "object", "title": "Playback" }, "PlaybackView": { "properties": { "speed": { "type": "number", "title": "Speed", "description": "Playback speed." }, "volume": { "type": "number", "title": "Volume", "description": "Volume multiplier." } }, "additionalProperties": false, "type": "object", "required": [ "speed", "volume" ], "title": "PlaybackView" }, "Position": { "properties": { "mode": { "type": "string", "enum": [ "fixed", "follow" ], "title": "Mode", "default": "fixed", "description": "fixed starts at frame; follow starts relative to clip_id." }, "frame": { "type": "integer", "maximum": 1036800000.0, "minimum": 0.0, "title": "Frame", "default": 0, "description": "Start frame for fixed positions." }, "clip_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Clip Id", "description": "Clip to follow. Required for follow positions." }, "edge": { "type": "string", "enum": [ "start", "end" ], "title": "Edge", "default": "start", "description": "Clip edge to follow: start or end." }, "offset": { "type": "integer", "maximum": 1036800000.0, "minimum": -1036800000.0, "title": "Offset", "default": 0, "description": "Frames added to the followed edge. Negative values start earlier." } }, "additionalProperties": false, "type": "object", "title": "Position" }, "ProjectCreate": { "properties": { "title": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Title", "default": "Untitled Project", "description": "Project title." }, "description": { "type": "string", "maxLength": 1000, "title": "Description", "default": "", "description": "Project description." }, "tts_settings": { "anyOf": [ { "$ref": "#/components/schemas/TtsSettings" }, { "type": "null" } ], "description": "TTS model and language settings." }, "default_voice_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Default Voice Id", "description": "Voice given to new clips that do not set voice_id." }, "default_instructions": { "type": "string", "maxLength": 1000, "title": "Default Instructions", "default": "", "description": "Delivery instructions for clips with empty instructions." }, "default_silence_ms": { "type": "integer", "maximum": 600000.0, "minimum": 0.0, "title": "Default Silence Ms", "default": 0, "description": "Silence after each clip in milliseconds, unless the clip sets trailing_silence_ms." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." } }, "additionalProperties": false, "type": "object", "required": [ "operation_id" ], "title": "ProjectCreate" }, "ProjectImport": { "properties": { "title": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Title", "default": "Untitled Project", "description": "Project title." }, "description": { "type": "string", "maxLength": 1000, "title": "Description", "default": "", "description": "Project description." }, "tts_settings": { "anyOf": [ { "$ref": "#/components/schemas/TtsSettings" }, { "type": "null" } ], "description": "TTS model and language settings." }, "default_voice_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Default Voice Id", "description": "Voice given to new clips that do not set voice_id." }, "default_instructions": { "type": "string", "maxLength": 1000, "title": "Default Instructions", "default": "", "description": "Delivery instructions for clips with empty instructions." }, "default_silence_ms": { "type": "integer", "maximum": 600000.0, "minimum": 0.0, "title": "Default Silence Ms", "default": 0, "description": "Silence after each clip in milliseconds, unless the clip sets trailing_silence_ms." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "chapters": { "items": { "$ref": "#/components/schemas/ImportChapter" }, "type": "array", "maxItems": 20, "minItems": 1, "title": "Chapters", "description": "Chapters in order, from 1 to 20." } }, "additionalProperties": false, "type": "object", "required": [ "operation_id", "chapters" ], "title": "ProjectImport" }, "ProjectList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ProjectView" }, "type": "array", "title": "Items", "description": "Resources in order." }, "total": { "type": "integer", "title": "Total", "description": "Total number of matching items." }, "page": { "type": "integer", "title": "Page", "description": "Current page number." }, "page_size": { "type": "integer", "title": "Page Size", "description": "Items per page." } }, "additionalProperties": false, "type": "object", "required": [ "items", "total", "page", "page_size" ], "title": "ProjectList" }, "ProjectPatch": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "title": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Title", "description": "Project title." }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Description", "description": "Project description." }, "tts_settings": { "anyOf": [ { "$ref": "#/components/schemas/TtsSettings" }, { "type": "null" } ], "description": "TTS model and language settings." }, "default_voice_id": { "anyOf": [ { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, { "type": "null" } ], "title": "Default Voice Id", "description": "Voice given to new clips that do not set voice_id." }, "default_instructions": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Default Instructions", "description": "Delivery instructions for clips with empty instructions." }, "default_silence_ms": { "anyOf": [ { "type": "integer", "maximum": 600000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Default Silence Ms", "description": "Silence after each clip in milliseconds, unless the clip sets trailing_silence_ms." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id" ], "title": "ProjectPatch" }, "ProjectResult": { "properties": { "project": { "$ref": "#/components/schemas/ProjectView", "description": "The project after this request." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." }, "client_refs": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Client Refs", "description": "Import only: each client_ref mapped to its created ID." }, "created_ids": { "items": { "type": "string" }, "type": "array", "title": "Created Ids", "description": "IDs created by this request, in order." } }, "additionalProperties": false, "type": "object", "required": [ "project", "edit_token" ], "title": "ProjectResult" }, "ProjectView": { "properties": { "id": { "type": "string", "title": "Id", "description": "Project ID." }, "title": { "type": "string", "title": "Title", "description": "Project title." }, "description": { "type": "string", "title": "Description", "description": "Project description." }, "tts_settings": { "anyOf": [ { "$ref": "#/components/schemas/TtsSettingsView" }, { "type": "null" } ], "description": "TTS model and language settings." }, "default_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Default Voice Id", "description": "Voice given to new clips that do not set voice_id." }, "default_instructions": { "type": "string", "title": "Default Instructions", "description": "Delivery instructions for clips with empty instructions." }, "default_silence_ms": { "type": "integer", "title": "Default Silence Ms", "description": "Silence after each clip in milliseconds, unless the clip sets trailing_silence_ms." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token." }, "created_at": { "type": "string", "title": "Created At", "description": "Creation time (ISO 8601)." }, "updated_at": { "type": "string", "title": "Updated At", "description": "Last update time (ISO 8601)." }, "chapter_count": { "type": "integer", "title": "Chapter Count", "description": "Number of active chapters." }, "clip_count": { "type": "integer", "title": "Clip Count", "description": "Number of clips in active chapters." } }, "additionalProperties": false, "type": "object", "required": [ "id", "title", "description", "tts_settings", "default_voice_id", "default_instructions", "default_silence_ms", "edit_token", "created_at", "updated_at", "chapter_count", "clip_count" ], "title": "ProjectView" }, "PronunciationDictionaryLocator": { "properties": { "pronunciation_dictionary_id": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Pronunciation Dictionary Id", "description": "Pronunciation dictionary identifier." }, "version_id": { "type": "string", "maxLength": 120, "minLength": 1, "title": "Version Id", "description": "Pronunciation dictionary version identifier." } }, "additionalProperties": false, "type": "object", "required": [ "pronunciation_dictionary_id", "version_id" ], "title": "PronunciationDictionaryLocator" }, "RealtimeTtsAudioFormat": { "properties": { "codec": { "type": "string", "title": "Codec", "default": "pcm_s16le" }, "sample_rate": { "type": "integer", "title": "Sample Rate", "default": 24000 }, "channels": { "type": "integer", "title": "Channels", "default": 1 }, "sample_width_bits": { "type": "integer", "title": "Sample Width Bits", "default": 16 } }, "type": "object", "title": "RealtimeTtsAudioFormat" }, "RealtimeTtsSessionRequest": { "properties": { "model_id": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Model Id", "description": "Model ID for speech generation. Selected automatically when omitted. See [List models](https://docs.breezeblue.ai/api-reference/models/list-models)." }, "language_code": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "Language Code", "description": "ISO 639-1 two-letter language code supported by the selected model. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Initial performance instructions, written in the same language as the input text. See [Updating instructions](https://docs.breezeblue.ai/guides/realtime-text-to-speech#update-instructions-between-turns)." }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/RealtimeTtsVoiceSettingsPayload" }, { "type": "null" } ], "description": "Optional realtime voice settings. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings)." }, "inactivity_timeout_seconds": { "anyOf": [ { "type": "integer", "maximum": 180.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Inactivity Timeout Seconds", "description": "Idle timeout for the WebSocket session. Defaults to 30 seconds and is capped at 180 seconds." }, "enable_logging": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Enable Logging", "description": "Whether realtime turns should be stored in generation history." } }, "additionalProperties": false, "type": "object", "title": "RealtimeTtsSessionRequest" }, "RealtimeTtsSessionResponse": { "properties": { "client_secret": { "type": "string", "title": "Client Secret", "description": "Short-lived token for browser WebSocket connections." }, "websocket_url": { "type": "string", "title": "Websocket Url", "description": "WebSocket URL including the client_secret query parameter." }, "direct_websocket_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Direct Websocket Url", "description": "Optional direct WebSocket URL without credentials in its query. Authenticate with the documented WebSocket subprotocols." }, "expires_at": { "type": "string", "title": "Expires At", "description": "ISO-8601 expiration timestamp for the client secret." }, "audio_format": { "$ref": "#/components/schemas/RealtimeTtsAudioFormat", "description": "Fixed realtime audio stream format." } }, "type": "object", "required": [ "client_secret", "websocket_url", "expires_at" ], "title": "RealtimeTtsSessionResponse" }, "RealtimeTtsVoiceSettingsPayload": { "properties": { "guidance_scale": { "anyOf": [ { "type": "number", "maximum": 10.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Guidance Scale", "description": "Generation guidance strength. Accepted range: 1.0 to 10.0. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings)." } }, "additionalProperties": false, "type": "object", "title": "RealtimeTtsVoiceSettingsPayload" }, "Reorder": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "ids": { "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "\\S" }, "type": "array", "maxItems": 10000, "minItems": 1, "title": "Ids", "description": "Every ID in the new order, each exactly once." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "ids" ], "title": "Reorder" }, "SaveVoicePreviewRequest": { "properties": { "gender": { "anyOf": [ { "type": "string", "enum": [ "male", "female", "neutral" ] }, { "type": "null" } ], "title": "Gender", "description": "Stable gender code, or null when not classified. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, "age": { "anyOf": [ { "type": "string", "enum": [ "child", "young", "middle_aged", "old" ] }, { "type": "null" } ], "title": "Age", "description": "Stable age code, or null when not classified. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, "tone": { "items": { "type": "string", "enum": [ "warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate" ] }, "type": "array", "maxItems": 3, "title": "Tone", "description": "Zero to three distinct stable tone codes. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options).", "uniqueItems": true }, "accent": { "anyOf": [ { "type": "string", "enum": [ "american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese" ] }, { "type": "null" } ], "title": "Accent", "description": "Stable accent code, or null. Valid only for en or zh and must match language_code. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options), [accent codes](https://docs.breezeblue.ai/concepts/multilingual#voices-and-accents)." }, "voice_name": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ], "title": "Voice Name", "description": "Display name, up to 80 characters. Clone previews default to their preview name; Remix previews default to the source voice name. Required for other preview types." }, "voice_description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "title": "Voice Description", "description": "Optional description stored with the saved voice. Remix previews default to the source description; an empty string clears it." }, "language_code": { "anyOf": [ { "type": "string", "enum": [ "af", "ar", "bg", "bn", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fr", "gl", "he", "hi", "hu", "id", "is", "it", "ja", "kn", "ko", "lt", "mr", "ms", "ne", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh" ] }, { "type": "null" } ], "title": "Language Code", "description": "Required saved audio language. Use a supported language code. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "tags": { "items": { "type": "string", "maxLength": 128 }, "type": "array", "maxItems": 20, "title": "Tags", "description": "Tags stored with the saved voice. Spelling is preserved; matching and deduplication ignore case. See [Tags and favorites](https://docs.breezeblue.ai/concepts/voices#tags-and-favorites)." } }, "additionalProperties": false, "type": "object", "title": "SaveVoicePreviewRequest" }, "TrackCreate": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "name": { "type": "string", "maxLength": 200, "minLength": 1, "title": "Name", "description": "Track name." }, "chapter_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Chapter Id", "description": "Limit the track to this chapter. Omit to span the whole project." }, "volume": { "type": "number", "maximum": 2.0, "minimum": 0.0, "title": "Volume", "default": 1, "description": "Track volume, from 0 to 2." }, "muted": { "type": "boolean", "title": "Muted", "default": false, "description": "Whether the track is muted." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id", "name" ], "title": "TrackCreate" }, "TrackList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/TrackView" }, "type": "array", "title": "Items", "description": "Resources in order." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." } }, "additionalProperties": false, "type": "object", "required": [ "items", "edit_token" ], "title": "TrackList" }, "TrackPatch": { "properties": { "expected_edit_token": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Expected Edit Token", "description": "edit_token from your latest read or write of this project. A stale token returns 409." }, "operation_id": { "type": "string", "format": "uuid", "title": "Operation Id", "description": "New UUID for each write. Retrying with the same ID and body returns the original result instead of repeating the write." }, "name": { "anyOf": [ { "type": "string", "maxLength": 200, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Track name." }, "chapter_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "title": "Chapter Id", "description": "Limit the track to this chapter. null spans the whole project." }, "volume": { "anyOf": [ { "type": "number", "maximum": 2.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Volume", "description": "Track volume, from 0 to 2." }, "muted": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Muted", "description": "Whether the track is muted." } }, "additionalProperties": false, "type": "object", "required": [ "expected_edit_token", "operation_id" ], "title": "TrackPatch" }, "TrackResult": { "properties": { "track": { "$ref": "#/components/schemas/TrackView", "description": "The track." }, "edit_token": { "type": "string", "title": "Edit Token", "description": "Current edit_token. Send it as expected_edit_token on the next write." } }, "additionalProperties": false, "type": "object", "required": [ "track", "edit_token" ], "title": "TrackResult" }, "TrackView": { "properties": { "id": { "type": "string", "title": "Id", "description": "Track ID; narration for the narration track." }, "name": { "type": "string", "title": "Name", "description": "Track name." }, "chapter_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Chapter Id", "description": "Chapter the track is limited to; null spans the whole project." }, "volume": { "type": "number", "title": "Volume", "default": 1, "description": "Track volume." }, "muted": { "type": "boolean", "title": "Muted", "default": false, "description": "Whether the track is muted." }, "readonly": { "type": "boolean", "title": "Readonly", "default": false, "description": "true for the narration track, which is edited through clips." }, "instances": { "items": { "$ref": "#/components/schemas/InstanceView" }, "type": "array", "title": "Instances", "description": "Audio instances on the track." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name" ], "title": "TrackView" }, "TtsConvertWithTimestampsRequest": { "properties": { "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Text to synthesize. Up to 1000 characters by default; accounts with an approved higher limit may send up to their configured limit, at most 2000 characters. See [Audio tags](https://docs.breezeblue.ai/guides/audio-tags)." }, "model_id": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Model Id", "description": "Model ID for speech generation. Selected automatically when omitted. See [List models](https://docs.breezeblue.ai/api-reference/models/list-models)." }, "language_code": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "Language Code", "description": "ISO 639-1 two-letter language code supported by the selected model. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Performance instructions, written in the same language as the input text. See [Expressive controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls), [Voice instruction prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting)." }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/TtsVoiceSettingsPayload" }, { "type": "null" } ], "description": "Optional per-request voice settings override. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings)." } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "TtsConvertWithTimestampsRequest", "description": "Speech with complete word timing; ordinary TTS fields only." }, "TtsEnhanceRequest": { "properties": { "instruction": { "type": "string", "minLength": 1, "title": "Instruction", "description": "Instruction text to enhance. Required and must be 1000 characters or fewer." }, "language_code": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "Language Code", "description": "Optional ISO 639-1 two-letter script language code. It does not change the enhanced instruction's language. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." } }, "additionalProperties": false, "type": "object", "required": [ "instruction" ], "title": "TtsEnhanceRequest" }, "TtsRequest": { "properties": { "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Text to synthesize. Up to 1000 characters by default; accounts with an approved higher limit may send up to their configured limit, at most 2000 characters. See [Audio tags](https://docs.breezeblue.ai/guides/audio-tags)." }, "model_id": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Model Id", "description": "Model ID for speech generation. Selected automatically when omitted. See [List models](https://docs.breezeblue.ai/api-reference/models/list-models)." }, "language_code": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "Language Code", "description": "ISO 639-1 two-letter language code supported by the selected model. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Performance instructions, written in the same language as the input text. See [Expressive controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls), [Voice instruction prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting)." }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/TtsVoiceSettingsPayload" }, { "type": "null" } ], "description": "Optional per-request voice settings override. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings)." } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "TtsRequest" }, "TtsSettings": { "properties": { "model": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ], "title": "Model", "description": "TTS model ID from List models." }, "language": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Language", "description": "Project language code." }, "generation_language": { "anyOf": [ { "type": "string", "maxLength": 2 }, { "type": "null" } ], "title": "Generation Language", "description": "Language code sent with each generation. null lets the model detect the language." }, "guidance_scale": { "anyOf": [ { "type": "number", "maximum": 10.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Guidance Scale", "description": "Generation guidance strength. Accepted range: 1.0 to 10.0. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings)." } }, "additionalProperties": false, "type": "object", "title": "TtsSettings" }, "TtsSettingsView": { "properties": { "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Model", "description": "TTS model ID from List models." }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Language", "description": "Project language code." }, "generation_language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generation Language", "description": "Language code sent with each generation. null lets the model detect the language." }, "guidance_scale": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Guidance Scale", "description": "Generation guidance strength. Accepted range: 1.0 to 10.0." } }, "additionalProperties": false, "type": "object", "title": "TtsSettingsView" }, "TtsVoiceSettingsPayload": { "properties": { "guidance_scale": { "anyOf": [ { "type": "number", "maximum": 10.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Guidance Scale", "description": "Generation guidance strength. Accepted range: 1.0 to 10.0. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings).", "default": 1.0 }, "speed": { "type": "number", "maximum": 2.0, "minimum": 0.5, "title": "Speed", "description": "Speech speed multiplier that preserves pitch. Range: 0.5–2.0; default: 1.0.", "default": 1.0 }, "volume": { "type": "number", "maximum": 2.0, "minimum": 0.01, "title": "Volume", "description": "Request-only linear amplitude multiplier. Range: 0.01–2.0 (1%–200%); default: 1.0. Values above 1.0 may clip peaks. Does not normalize loudness.", "default": 1.0 } }, "additionalProperties": false, "type": "object", "title": "TtsVoiceSettingsPayload" }, "TtsWithTimestampsRequest": { "properties": { "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Text to synthesize. Up to 1000 characters by default; accounts with an approved higher limit may send up to their configured limit, at most 2000 characters. See [Audio tags](https://docs.breezeblue.ai/guides/audio-tags)." }, "model_id": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Model Id", "description": "Model ID for speech generation. Selected automatically when omitted. See [List models](https://docs.breezeblue.ai/api-reference/models/list-models)." }, "language_code": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "Language Code", "description": "ISO 639-1 two-letter language code supported by the selected model. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Instructions", "description": "Performance instructions, written in the same language as the input text. See [Expressive controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls), [Voice instruction prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting)." }, "voice_settings": { "anyOf": [ { "$ref": "#/components/schemas/TtsVoiceSettingsPayload" }, { "type": "null" } ], "description": "Optional per-request voice settings override. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings)." }, "timestamp_mode": { "type": "string", "enum": [ "chunk", "lookahead" ], "title": "Timestamp Mode", "default": "chunk", "description": "See [Streaming timing modes](https://docs.breezeblue.ai/guides/speech-timing#streaming-audio-with-timing)." } }, "additionalProperties": false, "type": "object", "required": [ "text" ], "title": "TtsWithTimestampsRequest" }, "UpdateApiKeyRequest": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Updated display name for the API key." }, "credit_limit": { "anyOf": [ { "type": "number", "maximum": 1000000000.0, "minimum": 0.0 }, { "type": "null" } ], "title": "Credit Limit", "description": "Hard credit limit for this API key, or null for Unlimited. See [Credit budgets](https://docs.breezeblue.ai/authentication#credit-budgets)." } }, "additionalProperties": false, "type": "object", "title": "UpdateApiKeyRequest" }, "UploadResult": { "properties": { "upload_url": { "type": "string", "title": "Upload Url", "description": "Presigned URL. Upload the bytes with PUT." }, "headers": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Headers", "description": "Headers to send with the PUT request." }, "expires_in": { "type": "integer", "title": "Expires In", "description": "Seconds until upload_url expires." } }, "additionalProperties": false, "type": "object", "required": [ "upload_url", "expires_in" ], "title": "UploadResult" }, "VoiceDesignRequest": { "properties": { "voice_description": { "type": "string", "maxLength": 500, "minLength": 3, "title": "Voice Description", "description": "Text description of the desired voice. See [Voice Design prompting](https://docs.breezeblue.ai/guides/voice-design-prompting)." }, "text": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 3 }, { "type": "null" } ], "title": "Text", "description": "Optional preview script for the generated voice previews. See [Audio tags](https://docs.breezeblue.ai/guides/audio-tags)." }, "model_id": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Model Id", "description": "Model ID for speech generation. Selected automatically when omitted. See [List models](https://docs.breezeblue.ai/api-reference/models/list-models)." }, "language_code": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "Language Code", "description": "ISO 639-1 two-letter language code supported by the selected model. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "guidance_scale": { "anyOf": [ { "type": "number", "maximum": 10.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Guidance Scale", "description": "Generation guidance strength. Accepted range: 1.0 to 10.0. Random within this range when omitted. See [Voice Design controls](https://docs.breezeblue.ai/guides/voice-design#generate-synchronous-previews)." }, "preview_count": { "anyOf": [ { "type": "integer", "maximum": 3.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Preview Count", "description": "Number of preview variants to generate. Defaults to 1 and accepts values from 1 to 3." } }, "additionalProperties": false, "type": "object", "required": [ "voice_description" ], "title": "VoiceDesignRequest" }, "VoiceDesignStreamRequest": { "properties": { "voice_description": { "type": "string", "maxLength": 500, "minLength": 3, "title": "Voice Description", "description": "Text description of the desired voice. See [Voice Design prompting](https://docs.breezeblue.ai/guides/voice-design-prompting)." }, "text": { "anyOf": [ { "type": "string", "maxLength": 500, "minLength": 3 }, { "type": "null" } ], "title": "Text", "description": "Preview script. Breeze uses a default script when omitted. See [Audio tags](https://docs.breezeblue.ai/guides/audio-tags)." }, "model_id": { "anyOf": [ { "type": "string", "maxLength": 120, "minLength": 1 }, { "type": "null" } ], "title": "Model Id", "description": "Model ID for voice generation. See [List models](https://docs.breezeblue.ai/api-reference/models/list-models)." }, "language_code": { "anyOf": [ { "type": "string", "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ], "title": "Language Code", "description": "Optional ISO 639-1 two-letter preview language. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "guidance_scale": { "anyOf": [ { "type": "number", "maximum": 10.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Guidance Scale", "description": "Generation guidance strength. Accepted range: 1.0 to 10.0. Random within this range when omitted. See [Voice Design controls](https://docs.breezeblue.ai/guides/voice-design#generate-synchronous-previews)." } }, "additionalProperties": false, "type": "object", "required": [ "voice_description" ], "title": "VoiceDesignStreamRequest", "description": "Single-preview request contract for live PCM voice design audio." }, "VoiceLocalizePreviewRequest": { "properties": { "voice_id": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Voice Id", "description": "Source voice to localize. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, "language_code": { "type": "string", "maxLength": 16, "minLength": 2, "title": "Language Code", "description": "Target speaking language for the localized preview. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "name": { "anyOf": [ { "type": "string", "maxLength": 160, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "Display name for the preview. Defaults to the source voice name." } }, "additionalProperties": false, "type": "object", "required": [ "voice_id", "language_code" ], "title": "VoiceLocalizePreviewRequest", "description": "Localize an existing voice into another supported speaking language." }, "VoiceRemixPrepareRequest": { "properties": { "voice_id": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Voice Id", "description": "Your own or an available official voice ID. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, "prompt": { "anyOf": [ { "type": "string", "maxLength": 1000, "minLength": 3 }, { "type": "null" } ], "title": "Prompt", "description": "Desired voice change. Required unless preset_id selects a preset. Custom and edited preset descriptions are enhanced automatically." }, "preset_id": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Preset Id", "description": "ID from the remix preset catalog. An unchanged preset uses its curated instruction and script, translated when needed." } }, "additionalProperties": false, "type": "object", "required": [ "voice_id" ], "title": "VoiceRemixPrepareRequest", "description": "Prepare a custom description or a curated preset in the source language." }, "VoiceRemixPreviewRequest": { "properties": { "voice_id": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Voice Id", "description": "Owned or available official voice ID. Third-party favorites do not grant remix access. See [List voices](https://docs.breezeblue.ai/api-reference/voices/list-voices)." }, "prompt": { "anyOf": [ { "type": "string", "maxLength": 1000, "minLength": 3 }, { "type": "null" } ], "title": "Prompt", "description": "Desired voice change. Required unless preset_id selects a preset. Custom and edited preset descriptions are enhanced automatically." }, "preset_id": { "anyOf": [ { "type": "string", "maxLength": 64, "minLength": 1 }, { "type": "null" } ], "title": "Preset Id", "description": "ID from the remix preset catalog. An unchanged preset bypasses Enhance; language differences are translated faithfully." }, "guidance_scale": { "type": "number", "maximum": 10.0, "minimum": 1.0, "title": "Guidance Scale", "default": 4, "description": "Instruction following strength, 1–10. Default 4 (Expressive); 2 is Stable, 6 Creative, 8 Intense. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings)." }, "preparation_token": { "anyOf": [ { "type": "string", "maxLength": 24000, "minLength": 1 }, { "type": "null" } ], "title": "Preparation Token", "description": "Optional token from prepare. Reuse it with the same input to keep candidate instructions and scripts identical. Without it, input is prepared before generation." } }, "additionalProperties": false, "type": "object", "required": [ "voice_id" ], "title": "VoiceRemixPreviewRequest", "description": "Create one same-language candidate from an owned or official voice." }, "VoiceSettingsPayload": { "properties": { "guidance_scale": { "anyOf": [ { "type": "number", "maximum": 10.0, "minimum": 1.0 }, { "type": "null" } ], "title": "Guidance Scale", "description": "Generation guidance strength. Accepted range: 1.0 to 10.0. See [Voice settings](https://docs.breezeblue.ai/concepts/voices#voice-settings).", "default": 1.0 } }, "additionalProperties": false, "type": "object", "title": "VoiceSettingsPayload" }, "VoiceSummary": { "properties": { "id": { "type": "string", "title": "Id", "description": "Voice ID." }, "name": { "type": "string", "title": "Name", "description": "Voice name." }, "available": { "type": "boolean", "title": "Available", "description": "false when the voice was deleted or is no longer accessible." } }, "additionalProperties": false, "type": "object", "required": [ "id", "name", "available" ], "title": "VoiceSummary" }, "VoiceTagsUpdateRequest": { "properties": { "tags": { "items": { "type": "string", "maxLength": 128 }, "type": "array", "maxItems": 20, "title": "Tags", "description": "Tags to store. Spelling is preserved; values that differ only by case are duplicates. Maximum 20 values and 128 characters each. See [Tags and favorites](https://docs.breezeblue.ai/concepts/voices#tags-and-favorites)." } }, "additionalProperties": false, "type": "object", "title": "VoiceTagsUpdateRequest" }, "ModelLanguageResponse": { "properties": { "language_id": { "title": "Language Id", "type": "string" }, "name": { "title": "Name", "type": "string" } }, "required": [ "language_id", "name" ], "title": "ModelLanguageResponse", "type": "object" }, "ModelResponse": { "properties": { "model_id": { "title": "Model Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "languages": { "items": { "$ref": "#/components/schemas/ModelLanguageResponse" }, "title": "Languages", "type": "array" }, "description": { "description": "Human-readable summary of the model.", "title": "Description", "type": "string" } }, "required": [ "model_id", "name", "description" ], "title": "ModelResponse", "type": "object" }, "ErrorResponse": { "properties": { "ok": { "default": false, "title": "Ok", "type": "boolean" }, "code": { "title": "Code", "type": "string" }, "detail": { "title": "Detail", "type": "string" }, "error": { "title": "Error", "type": "string" }, "meta": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Meta" } }, "required": [ "code", "detail", "error" ], "title": "ErrorResponse", "type": "object" }, "ValidationErrorResponse": { "properties": { "ok": { "default": false, "title": "Ok", "type": "boolean" }, "code": { "title": "Code", "type": "string" }, "detail": { "title": "Detail", "type": "string" }, "error": { "title": "Error", "type": "string" }, "meta": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Meta" } }, "required": [ "code", "detail", "error" ], "title": "ValidationErrorResponse", "type": "object" }, "AsyncTtsJobResponse": { "properties": { "generation_job_id": { "title": "Generation Job Id", "type": "string" }, "history_item_id": { "title": "History Item Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "generation_job_id", "history_item_id", "status" ], "title": "AsyncTtsJobResponse", "type": "object" }, "WordTimestampResponse": { "properties": { "index": { "description": "Word/token index, shared across fragments of the same word.", "minimum": 0, "title": "Index", "type": "integer" }, "word": { "title": "Word", "type": "string" }, "start": { "description": "Start in seconds from the generated audio origin.", "minimum": 0, "title": "Start", "type": "number" }, "end": { "description": "End in seconds from the generated audio origin.", "minimum": 0, "title": "End", "type": "number" } }, "required": [ "index", "word", "start", "end" ], "title": "WordTimestampResponse", "type": "object" }, "SpeechWithTimestampsResponse": { "properties": { "audio_base64": { "description": "Complete audio encoded as base64. Decode before saving or playback. See [Decode audio and timing](https://docs.breezeblue.ai/guides/speech-timing).", "title": "Audio Base64", "type": "string" }, "content_type": { "description": "MIME type of the decoded audio, matching output_format.", "title": "Content Type", "type": "string" }, "word_timestamps": { "description": "Complete word/token list, relative to the delivered audio in seconds. See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing).", "items": { "$ref": "#/components/schemas/WordTimestampResponse" }, "title": "Word Timestamps", "type": "array" } }, "required": [ "audio_base64", "content_type", "word_timestamps" ], "title": "SpeechWithTimestampsResponse", "type": "object" }, "GenerationJobAudioFormatResponse": { "additionalProperties": true, "properties": { "encoding": { "title": "Encoding", "type": "string" }, "codec": { "title": "Codec", "type": "string" }, "channels": { "title": "Channels", "type": "integer" }, "sample_rate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Sample Rate" }, "sample_width_bits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Sample Width Bits" }, "bitrate_kbps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Bitrate Kbps" } }, "required": [ "encoding", "codec", "channels" ], "title": "GenerationJobAudioFormatResponse", "type": "object" }, "GenerationJobErrorResponse": { "properties": { "code": { "title": "Code", "type": "string" }, "detail": { "title": "Detail", "type": "string" } }, "required": [ "code", "detail" ], "title": "GenerationJobErrorResponse", "type": "object" }, "GenerationJobResponse": { "additionalProperties": true, "properties": { "generation_job_id": { "title": "Generation Job Id", "type": "string" }, "history_item_id": { "title": "History Item Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "state": { "title": "State", "type": "string" }, "source": { "title": "Source", "type": "string" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Voice Id" }, "voice_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Voice Name" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin" }, "model_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model Id" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Type" }, "output_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Output Format" }, "audio_format": { "anyOf": [ { "$ref": "#/components/schemas/GenerationJobAudioFormatResponse" }, { "type": "null" } ], "default": null }, "word_timestamps": { "anyOf": [ { "items": { "$ref": "#/components/schemas/WordTimestampResponse" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Complete word/token timestamps in seconds relative to the delivered audio. Present when a timestamp job is ready; omitted for ordinary or unfinished jobs. See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing).", "title": "Word Timestamps" }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Download Url" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "date_unix": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Date Unix" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/GenerationJobErrorResponse" }, { "type": "null" } ], "default": null } }, "required": [ "generation_job_id", "history_item_id", "status", "state", "source" ], "title": "GenerationJobResponse", "type": "object" }, "SpeechTimingChunkResponse": { "properties": { "audio_base64": { "description": "Base64 audio bytes; may be empty for metadata-only updates. See [Decode audio and timing](https://docs.breezeblue.ai/guides/speech-timing).", "title": "Audio Base64", "type": "string" }, "word_timestamps": { "items": { "$ref": "#/components/schemas/WordTimestampResponse" }, "title": "Word Timestamps", "type": "array", "description": "See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing)." } }, "required": [ "audio_base64", "word_timestamps" ], "title": "SpeechTimingChunkResponse", "type": "object" }, "RealtimeTtsAudioFormatResponse": { "properties": { "codec": { "default": "pcm_s16le", "title": "Codec", "type": "string" }, "sample_rate": { "default": 24000, "title": "Sample Rate", "type": "integer" }, "channels": { "default": 1, "title": "Channels", "type": "integer" }, "sample_width_bits": { "default": 16, "title": "Sample Width Bits", "type": "integer" } }, "title": "RealtimeTtsAudioFormatResponse", "type": "object" }, "TtsEnhanceResponse": { "properties": { "instruction": { "title": "Instruction", "type": "string" }, "language_code": { "title": "Language Code", "type": "string", "description": "See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." } }, "required": [ "instruction", "language_code" ], "title": "TtsEnhanceResponse", "type": "object" }, "VoiceMetadataOptionsResponse": { "properties": { "language_codes": { "description": "Supported language_code values in canonical order.", "items": { "enum": [ "af", "ar", "bg", "bn", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fr", "gl", "he", "hi", "hu", "id", "is", "it", "ja", "kn", "ko", "lt", "mr", "ms", "ne", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh" ], "type": "string" }, "title": "Language Codes", "type": "array" }, "gender_codes": { "items": { "enum": [ "male", "female", "neutral" ], "type": "string" }, "title": "Gender Codes", "type": "array" }, "age_codes": { "items": { "enum": [ "child", "young", "middle_aged", "old" ], "type": "string" }, "title": "Age Codes", "type": "array" }, "tone_codes": { "items": { "enum": [ "warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate" ], "type": "string" }, "title": "Tone Codes", "type": "array" }, "tone_max_items": { "description": "Maximum number of distinct tone codes accepted for one voice.", "examples": [ 3 ], "title": "Tone Max Items", "type": "integer" }, "accent_codes_by_language": { "additionalProperties": { "items": { "enum": [ "american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese" ], "type": "string" }, "type": "array" }, "description": "Accent codes keyed by every supported language_code. Languages without accent choices have an empty array. Chinese has eight non-null codes; Mandarin is represented by null. Null English accents are treated as American English.", "title": "Accent Codes By Language", "type": "object" } }, "required": [ "language_codes", "gender_codes", "age_codes", "tone_codes", "tone_max_items", "accent_codes_by_language" ], "title": "VoiceMetadataOptionsResponse", "type": "object" }, "VoiceResponse": { "additionalProperties": true, "properties": { "voice_id": { "title": "Voice Id", "type": "string" }, "name": { "description": "Display name for the authenticated account. A saved public voice uses the personal alias set in Voice Library, when present.", "title": "Name", "type": "string" }, "origin": { "title": "Origin", "type": "string" }, "voice_type": { "title": "Voice Type", "type": "string" }, "tags": { "items": { "type": "string", "maxLength": 128 }, "maxItems": 20, "title": "Tags", "type": "array" }, "is_favorited": { "default": false, "title": "Is Favorited", "type": "boolean" }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Url" }, "settings": { "$ref": "#/components/schemas/VoiceSettingsResponse" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "language_code": { "enum": [ "af", "ar", "bg", "bn", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fr", "gl", "he", "hi", "hu", "id", "is", "it", "ja", "kn", "ko", "lt", "mr", "ms", "ne", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh" ], "title": "Language Code", "type": "string", "description": "See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "gender": { "anyOf": [ { "enum": [ "male", "female", "neutral" ], "type": "string" }, { "type": "null" } ], "title": "Gender" }, "age": { "anyOf": [ { "enum": [ "child", "young", "middle_aged", "old" ], "type": "string" }, { "type": "null" } ], "title": "Age" }, "tone": { "items": { "type": "string", "enum": [ "warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate" ] }, "maxItems": 3, "title": "Tone", "type": "array", "uniqueItems": true }, "accent": { "anyOf": [ { "enum": [ "american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese", "mandarin_guangdong", "mandarin_yunnan" ], "type": "string" }, { "type": "null" } ], "title": "Accent" }, "publication_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Owner-only publication review state: queued, processing, published, needs_review, failed, or superseded. Null when unavailable.", "title": "Publication Status" }, "publication_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Publication Job Id" }, "publication_error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Publication Error Code" }, "created_at_unix": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Created At Unix" } }, "required": [ "voice_id", "name", "origin", "voice_type", "settings", "language_code", "gender", "age", "tone", "accent" ], "title": "VoiceResponse", "type": "object" }, "VoiceSettingsResponse": { "properties": { "guidance_scale": { "default": 1.0, "title": "Guidance Scale", "type": "number" } }, "title": "VoiceSettingsResponse", "type": "object" }, "VoiceListResponse": { "properties": { "voices": { "items": { "$ref": "#/components/schemas/VoiceResponse" }, "title": "Voices", "type": "array" }, "has_more": { "title": "Has More", "type": "boolean" }, "next_page_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Page Token" }, "total": { "title": "Total", "type": "integer" }, "page": { "title": "Page", "type": "integer" }, "page_size": { "title": "Page Size", "type": "integer" } }, "required": [ "voices", "has_more", "total", "page", "page_size" ], "title": "VoiceListResponse", "type": "object" }, "VoiceEditStatusResponse": { "properties": { "status": { "title": "Status", "type": "string" }, "visibility": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Remains private while asynchronous publication is pending.", "title": "Visibility" }, "publication_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Publication Status" }, "publication_job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Publication Job Id" } }, "required": [ "status" ], "title": "VoiceEditStatusResponse", "type": "object" }, "GenericStatusResponse": { "properties": { "status": { "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "GenericStatusResponse", "type": "object" }, "VoiceClonePreviewResponse": { "properties": { "generated_voice_id": { "title": "Generated Voice Id", "type": "string" }, "requires_verification": { "default": false, "title": "Requires Verification", "type": "boolean" } }, "required": [ "generated_voice_id" ], "title": "VoiceClonePreviewResponse", "type": "object" }, "VoiceDesignPreviewResponse": { "properties": { "generated_voice_id": { "title": "Generated Voice Id", "type": "string" }, "audio_base_64": { "title": "Audio Base 64", "type": "string" }, "media_type": { "title": "Media Type", "type": "string" }, "duration_secs": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Duration Secs" } }, "required": [ "generated_voice_id", "audio_base_64", "media_type" ], "title": "VoiceDesignPreviewResponse", "type": "object" }, "VoiceDesignResponse": { "properties": { "previews": { "items": { "$ref": "#/components/schemas/VoiceDesignPreviewResponse" }, "title": "Previews", "type": "array" }, "text": { "title": "Text", "type": "string" } }, "required": [ "previews", "text" ], "title": "VoiceDesignResponse", "type": "object" }, "VoiceRemixPresetResponse": { "properties": { "id": { "title": "Id", "type": "string" }, "category": { "title": "Category", "type": "string" }, "name": { "title": "Name", "type": "string" }, "prompt": { "title": "Prompt", "type": "string" }, "script": { "title": "Script", "type": "string" }, "language": { "title": "Language", "type": "string" }, "guidance_scale": { "title": "Guidance Scale", "type": "number" }, "preview_audio_url": { "title": "Preview Audio Url", "type": "string" } }, "required": [ "id", "category", "name", "prompt", "script", "language", "guidance_scale", "preview_audio_url" ], "title": "VoiceRemixPresetResponse", "type": "object" }, "VoiceRemixPresetsResponse": { "properties": { "presets": { "items": { "$ref": "#/components/schemas/VoiceRemixPresetResponse" }, "title": "Presets", "type": "array" }, "example_voice_id": { "title": "Example Voice Id", "type": "string" } }, "required": [ "presets", "example_voice_id" ], "title": "VoiceRemixPresetsResponse", "type": "object" }, "VoiceRemixSourceResponse": { "properties": { "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Voice Id" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Name" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" } }, "title": "VoiceRemixSourceResponse", "type": "object" }, "VoiceRemixPreparationResponse": { "properties": { "preparation_token": { "description": "Valid for 24 hours for the same account, source, language, prompt and preset. Reuse across candidate strengths.", "title": "Preparation Token", "type": "string" }, "language_code": { "title": "Language Code", "type": "string", "description": "See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "instruction": { "title": "Instruction", "type": "string" }, "text": { "title": "Text", "type": "string" }, "source_voice": { "$ref": "#/components/schemas/VoiceRemixSourceResponse" } }, "required": [ "preparation_token", "language_code", "instruction", "text", "source_voice" ], "title": "VoiceRemixPreparationResponse", "type": "object" }, "VoiceRemixPreviewJobResponse": { "properties": { "generation_job_id": { "title": "Generation Job Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "generation_job_id", "status" ], "title": "VoiceRemixPreviewJobResponse", "type": "object" }, "VoiceRemixPreviewStatusResponse": { "properties": { "generation_job_id": { "title": "Generation Job Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "language_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Language the remixed preview speaks, once the job is ready. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual).", "title": "Language Code" }, "generated_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Preview ID to audition and save, available once the job is ready.", "title": "Generated Voice Id" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Script the remixed preview reads.", "title": "Text" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/GenerationJobErrorResponse" }, { "type": "null" } ], "default": null }, "instruction": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Prepared performance instruction used for this candidate.", "title": "Instruction" }, "guidance_scale": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Guidance Scale" }, "source_voice": { "anyOf": [ { "$ref": "#/components/schemas/VoiceRemixSourceResponse" }, { "type": "null" } ], "default": null }, "comparison_audio_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Existing source recording for comparison; its transcript is comparison_text.", "title": "Comparison Audio Url" }, "comparison_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Comparison Text" } }, "required": [ "generation_job_id", "status" ], "title": "VoiceRemixPreviewStatusResponse", "type": "object" }, "VoiceLocalizePreviewJobResponse": { "properties": { "generation_job_id": { "title": "Generation Job Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "generation_job_id", "status" ], "title": "VoiceLocalizePreviewJobResponse", "type": "object" }, "VoiceLocalizePreviewStatusResponse": { "properties": { "generation_job_id": { "title": "Generation Job Id", "type": "string" }, "status": { "title": "Status", "type": "string" }, "language_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Language the localized preview speaks, once the job is ready. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual).", "title": "Language Code" }, "generated_voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Preview ID to audition and save, available once the job is ready.", "title": "Generated Voice Id" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Script the localized preview reads.", "title": "Text" }, "error": { "anyOf": [ { "$ref": "#/components/schemas/GenerationJobErrorResponse" }, { "type": "null" } ], "default": null } }, "required": [ "generation_job_id", "status" ], "title": "VoiceLocalizePreviewStatusResponse", "type": "object" }, "SavedVoiceResponse": { "properties": { "voice_id": { "title": "Voice Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "origin": { "title": "Origin", "type": "string" }, "tags": { "items": { "type": "string", "maxLength": 128 }, "maxItems": 20, "title": "Tags", "type": "array" }, "is_favorited": { "default": false, "title": "Is Favorited", "type": "boolean" }, "preview_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Preview Url" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "language_code": { "enum": [ "af", "ar", "bg", "bn", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fr", "gl", "he", "hi", "hu", "id", "is", "it", "ja", "kn", "ko", "lt", "mr", "ms", "ne", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh" ], "title": "Language Code", "type": "string", "description": "See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "gender": { "anyOf": [ { "enum": [ "male", "female", "neutral" ], "type": "string" }, { "type": "null" } ], "title": "Gender" }, "age": { "anyOf": [ { "enum": [ "child", "young", "middle_aged", "old" ], "type": "string" }, { "type": "null" } ], "title": "Age" }, "tone": { "items": { "type": "string", "enum": [ "warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate" ] }, "maxItems": 3, "title": "Tone", "type": "array", "uniqueItems": true }, "accent": { "anyOf": [ { "enum": [ "american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese", "mandarin_guangdong", "mandarin_yunnan" ], "type": "string" }, { "type": "null" } ], "title": "Accent" }, "created_at_unix": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Created At Unix" } }, "required": [ "voice_id", "name", "origin", "language_code", "gender", "age", "tone", "accent" ], "title": "SavedVoiceResponse", "type": "object" }, "HistoryItemResponse": { "additionalProperties": true, "properties": { "history_item_id": { "title": "History Item Id", "type": "string" }, "voice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Voice Id" }, "voice_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Voice Name" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Origin" }, "model_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model Id" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" }, "source": { "title": "Source", "type": "string" }, "state": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "State" }, "content_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Content Type" }, "date_unix": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Date Unix" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Request Id" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Latency Ms" }, "http_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Http Status" }, "billable_units": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Billable Units" }, "cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost" }, "cost_millicredits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Cost Millicredits" } }, "required": [ "history_item_id", "source" ], "title": "HistoryItemResponse", "type": "object" }, "HistoryListResponse": { "properties": { "history": { "items": { "$ref": "#/components/schemas/HistoryItemResponse" }, "title": "History", "type": "array" }, "has_more": { "title": "Has More", "type": "boolean" }, "last_history_item_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last History Item Id" }, "total": { "title": "Total", "type": "integer" }, "page": { "title": "Page", "type": "integer" }, "page_size": { "title": "Page Size", "type": "integer" } }, "required": [ "history", "has_more", "total", "page", "page_size" ], "title": "HistoryListResponse", "type": "object" }, "BalanceTopupResponse": { "additionalProperties": true, "properties": { "topup_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Topup Id" }, "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Amount" }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Status" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" } }, "title": "BalanceTopupResponse", "type": "object" }, "BalanceResponse": { "additionalProperties": true, "properties": { "balance": { "title": "Balance", "type": "number" }, "balance_millicredits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Balance Millicredits" }, "topups": { "items": { "$ref": "#/components/schemas/BalanceTopupResponse" }, "title": "Topups", "type": "array" } }, "required": [ "balance" ], "title": "BalanceResponse", "type": "object" }, "EntitlementsResponse": { "additionalProperties": true, "properties": { "plan_code": { "title": "Plan Code", "type": "string" }, "max_concurrent_generations": { "title": "Max Concurrent Generations", "type": "integer" } }, "required": [ "plan_code", "max_concurrent_generations" ], "title": "EntitlementsResponse", "type": "object" }, "UsageDailyBucketResponse": { "properties": { "date": { "title": "Date", "type": "string" }, "request_count": { "title": "Request Count", "type": "integer" } }, "required": [ "date", "request_count" ], "title": "UsageDailyBucketResponse", "type": "object" }, "UsageItemResponse": { "additionalProperties": true, "properties": { "id": { "title": "Id", "type": "string" }, "endpoint": { "title": "Endpoint", "type": "string" }, "method": { "title": "Method", "type": "string" }, "status": { "title": "Status", "type": "integer" }, "api_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Key Id" }, "api_key_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Key Name" }, "api_key_prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Key Prefix" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Model" }, "billable_units": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Billable Units" }, "cost": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Cost" }, "cost_millicredits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Cost Millicredits" }, "latency_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Time to first audio for streaming audio requests, in milliseconds.", "title": "Latency Ms" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Generated audio duration, in milliseconds.", "title": "Duration Ms" }, "first_audio_chunk_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Compatibility alias for streaming time to first audio, in milliseconds.", "title": "First Audio Chunk Ms" }, "request_duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Developer API request duration, in milliseconds.", "title": "Request Duration Ms" }, "trace_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Trace Id" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Request Id" }, "text_characters": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Text Characters" }, "action_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Action Code" }, "client_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Type" }, "client_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Name" }, "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Client Version" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" } }, "required": [ "id", "endpoint", "method", "status" ], "title": "UsageItemResponse", "type": "object" }, "UsageSummaryResponse": { "properties": { "request_count": { "default": 0, "title": "Request Count", "type": "integer" }, "total_text_characters": { "default": 0, "title": "Total Text Characters", "type": "integer" }, "total_billable_units": { "default": 0, "title": "Total Billable Units", "type": "integer" }, "total_cost": { "default": 0, "title": "Total Cost", "type": "number" }, "total_cost_millicredits": { "default": 0, "title": "Total Cost Millicredits", "type": "integer" } }, "title": "UsageSummaryResponse", "type": "object" }, "UsageResponse": { "additionalProperties": true, "properties": { "window_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Window Days" }, "summary": { "$ref": "#/components/schemas/UsageSummaryResponse" }, "total": { "title": "Total", "type": "integer" }, "page": { "title": "Page", "type": "integer" }, "page_size": { "title": "Page Size", "type": "integer" }, "daily": { "items": { "$ref": "#/components/schemas/UsageDailyBucketResponse" }, "title": "Daily", "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/UsageItemResponse" }, "title": "Items", "type": "array" } }, "required": [ "summary", "total", "page", "page_size" ], "title": "UsageResponse", "type": "object" }, "ApiKeyResponse": { "additionalProperties": true, "properties": { "key_id": { "title": "Key Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "status": { "title": "Status", "type": "string" }, "api_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Api Key" }, "prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Prefix" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Used At" }, "disabled_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Disabled At" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Expires At" }, "rotated_from_key_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rotated From Key Id" }, "rotated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Rotated At" }, "credit_limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Credit Limit" }, "credit_used": { "default": 0, "title": "Credit Used", "type": "number" }, "credit_reserved": { "default": 0, "title": "Credit Reserved", "type": "number" }, "credit_remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Credit Remaining" }, "credit_budget_reset_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Credit Budget Reset At" } }, "required": [ "key_id", "name", "status" ], "title": "ApiKeyResponse", "type": "object" }, "ApiKeyListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiKeyResponse" }, "title": "Items", "type": "array" }, "total": { "title": "Total", "type": "integer" }, "page": { "title": "Page", "type": "integer" }, "page_size": { "title": "Page Size", "type": "integer" } }, "required": [ "items", "total", "page", "page_size" ], "title": "ApiKeyListResponse", "type": "object" }, "CurrentApiKey": { "properties": { "id": { "description": "Public API key identifier (key_id).", "title": "Id", "type": "string" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" }, "status": { "description": "Key status: active or expiring.", "title": "Status", "type": "string" }, "credit_limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Key Budget limit in credits; null when the key has no finite budget.", "title": "Credit Limit" }, "credit_used": { "default": 0, "description": "Credits captured against the key since its last reset.", "title": "Credit Used", "type": "number" }, "credit_reserved": { "default": 0, "description": "Credits reserved by in-flight requests on this key.", "title": "Credit Reserved", "type": "number" }, "credit_remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Credits still available on the key (limit - used - reserved, floored at 0); null when the key has no finite budget.", "title": "Credit Remaining" } }, "required": [ "id", "name", "prefix", "status" ], "title": "CurrentApiKey", "type": "object" }, "CurrentApiKeyResponse": { "properties": { "api_key": { "$ref": "#/components/schemas/CurrentApiKey" } }, "required": [ "api_key" ], "title": "CurrentApiKeyResponse", "type": "object" }, "VoicesEditRequestBody": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 80, "minLength": 1 }, { "type": "null" } ], "title": "Name", "description": "New display name. Maximum 80 characters." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "New description." }, "tags": { "anyOf": [ { "items": { "type": "string", "maxLength": 128 }, "type": "array", "maxItems": 20 }, { "type": "null" } ], "title": "Tags", "description": "See [Tags and favorites](https://docs.breezeblue.ai/concepts/voices#tags-and-favorites)." }, "language_code": { "anyOf": [ { "type": "string", "enum": [ "af", "ar", "bg", "bn", "bs", "ca", "cs", "da", "de", "el", "en", "es", "et", "eu", "fa", "fi", "fr", "gl", "he", "hi", "hu", "id", "is", "it", "ja", "kn", "ko", "lt", "mr", "ms", "ne", "nl", "no", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sv", "sw", "ta", "te", "th", "tl", "tr", "uk", "ur", "vi", "zh" ] }, { "type": "null" } ], "title": "Language Code", "description": "Saved audio language. Use a supported language code. See [supported language codes](https://docs.breezeblue.ai/concepts/multilingual)." }, "gender": { "anyOf": [ { "type": "string", "enum": [ "male", "female", "neutral" ] }, { "type": "null" } ], "title": "Gender", "description": "Stable gender code. Empty string clears the value. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, "age": { "anyOf": [ { "type": "string", "enum": [ "child", "young", "middle_aged", "old" ] }, { "type": "null" } ], "title": "Age", "description": "Stable age code. Empty string clears the value. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, "tone": { "anyOf": [ { "items": { "type": "string", "enum": [ "warm", "calm", "bright", "gentle", "energetic", "authoritative", "sincere", "weary", "precise", "refined", "urgent", "friendly", "articulate", "steady", "playful", "compassionate", "reflective", "measured", "rhythmic", "passionate" ] }, "type": "array", "maxItems": 3, "uniqueItems": true }, { "type": "null" } ], "title": "Tone", "description": "Repeat this field for up to three distinct tone codes. One empty field clears the array. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options)." }, "accent": { "anyOf": [ { "type": "string", "enum": [ "american", "british", "scottish", "irish", "australian", "canadian", "us_southern", "us_new_york", "indian", "south_african", "russian", "japanese", "korean", "chinese", "mandarin_northeastern", "mandarin_shaanxi", "mandarin_shanghai", "mandarin_sichuan", "mandarin_henan", "mandarin_beijing", "mandarin_taiwan", "cantonese" ] }, { "type": "null" } ], "title": "Accent", "description": "Stable accent code. Valid only for en or zh and must match language_code. Empty string clears the value. See [Metadata options](https://docs.breezeblue.ai/api-reference/voices/list-voice-metadata-options), [accent codes](https://docs.breezeblue.ai/concepts/multilingual#voices-and-accents)." } }, "type": "object", "title": "Body_edit_voice_v1_voices__voice_id__patch" }, "VoicePreviewsCloneRequestBody": { "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ], "title": "Name", "description": "Display name for the clone preview. Maximum 80 characters." }, "files": { "items": { "type": "string", "contentMediaType": "application/octet-stream" }, "type": "array", "minItems": 1, "maxItems": 1, "title": "Files", "description": "One reference audio file: WAV or MP3, at least 3 seconds, up to 5 MB." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description", "description": "Description stored with the preview." } }, "type": "object", "title": "Body_add_voice_v1_voice_previews_clone_post", "required": [ "files" ] } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "xi-api-key", "description": "Breeze Developer API key." } } }, "tags": [ { "name": "Models", "description": "Supported TTS models." }, { "name": "Text to Speech", "description": "Text-to-speech synthesis and instruction enhancement." }, { "name": "Voices", "description": "Saved voices and voice settings." }, { "name": "Voice Previews", "description": "Create, audition, and save temporary voice previews." }, { "name": "Account", "description": "Balance, usage, and API keys." }, { "name": "History", "description": "Generated audio history." }, { "name": "Studio", "description": "Projects, scripts, arrangement and audio materials." } ], "servers": [ { "url": "https://api.breeze.blue" } ] }