[{"data":1,"prerenderedAt":155},["ShallowReactive",2],{"reference-detail-en-clone_voice_api_v1_voice_post":3,"developer-code-1b5i8vu":153,"developer-code-m4wzi8":154},{"tag":4,"sourceTag":4,"tagSlug":5,"method":6,"path":7,"slug":8,"summary":9,"description":10,"operationId":11,"groupOrder":12,"descriptionHtml":13,"parameters":14,"requestBody":22,"responses":54,"security":140,"codeSamples":143},"Voices","voices","POST","\u002Fapi\u002Fv1\u002Fvoice","clone-voice","Clone voice","Clone a voice from a clean audio sample (AVI\u002FMP3\u002FMP4\u002FM4A\u002FWAV, up to 30MB) and get a reusable\n`voice_id`. Cloning runs synchronously and can take a while, so set a generous request timeout. The\nnumber of active cloned voices allowed depends on your plan.","clone_voice_api_v1_voice_post",30,"\u003Cp>Clone a voice from a clean audio sample (AVI\u002FMP3\u002FMP4\u002FM4A\u002FWAV, up to 30MB) and get a reusable \u003Ccode>voice_id\u003C\u002Fcode>. Cloning runs synchronously and can take a while, so set a generous request timeout. The number of active cloned voices allowed depends on your plan.\u003C\u002Fp>",[15],{"name":16,"in":17,"required":18,"description":19,"type":20,"example":21},"X-API-Key","header",true,"Your VisionStory API key (`sk-vs-...`), kept server-side. Create or manage keys in [API keys](\u002Fapi-keys) (Pro plan and up).","string","sk-vs-your-api-key",{"required":18,"contentType":23,"schema":24,"example":51},"application\u002Fjson",{"type":25,"description":26,"nullable":27,"properties":28},"CloneVoiceRequest","",false,[29,34,47],{"name":30,"required":27,"type":31,"description":32,"nullable":18,"properties":33},"audio_url","string | null","Publicly reachable URL of a clean voice sample. Provide either this or `inline_data`. Formats: AVI\u002FMP3\u002FMP4\u002FM4A\u002FWAV, up to 30MB.",[],{"name":35,"required":27,"type":36,"description":37,"nullable":18,"properties":38},"inline_data","InlineDataModel | null","Voice sample as inline base64 data. Provide either this or `audio_url`.",[39,43],{"name":40,"required":18,"type":20,"description":41,"nullable":27,"properties":42},"data","The file's raw bytes encoded as a base64 string (no `data:` URI prefix).",[],{"name":44,"required":18,"type":20,"description":45,"nullable":27,"properties":46},"mime_type","MIME type of the inline data; the gateway uses it to tell image \u002F audio \u002F video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav'] and images ['image\u002Fjpeg', 'image\u002Fjpg', 'image\u002Fpng', 'image\u002Fwebp', 'image\u002Fheic'].",[],{"name":48,"required":27,"type":31,"description":49,"nullable":18,"properties":50},"preview_text","Text spoken in the generated preview clip for the cloned voice. Defaults to a built-in phrase. Max 100 characters.",[],{"audio_url":52,"preview_text":53},"https:\u002F\u002Fexample.com\u002Fmedia\u002Fvoice-sample.mp3","Welcome to VisionStory.",[55,110],{"status":56,"description":57,"contentType":23,"schema":58,"example":95,"examples":103,"headers":109},"200","Successful Response",{"type":59,"description":26,"nullable":27,"properties":60},"BaseSuccessResponse_CloneVoiceResponse_",[61,85,90],{"name":40,"required":18,"type":62,"description":63,"nullable":18,"properties":64},"CloneVoiceResponse | null","The endpoint-specific payload. See this endpoint's response schema for its fields; null only when the operation returns no payload.",[65,69,73,77,81],{"name":66,"required":27,"type":20,"description":67,"nullable":27,"default":26,"properties":68},"gender","Voice gender detected from the audio sample; empty if detection is still pending.",[],{"name":70,"required":27,"type":20,"description":71,"nullable":27,"default":26,"properties":72},"language","Primary language detected from the audio sample, e.g. `english`; empty if detection is still pending.",[],{"name":74,"required":27,"type":20,"description":75,"nullable":27,"default":26,"properties":76},"locale","BCP 47 locale detected for the clone (e.g. `en-US`), same vocabulary as the `locale` field of GET \u002Fapi\u002Fv1\u002Fvoices and the `locale` parameter of POST \u002Fapi\u002Fv1\u002Ftts; empty if detection was unavailable.",[],{"name":78,"required":27,"type":20,"description":79,"nullable":27,"default":26,"properties":80},"preview_audio_url","URL of a short sample clip synthesized with the cloned voice; empty if not ready yet.",[],{"name":82,"required":18,"type":20,"description":83,"nullable":27,"properties":84},"voice_id","Unique identifier of the cloned voice. Pass it as `voice_id` in a text script to speak with this voice.",[],{"name":86,"required":27,"type":20,"description":87,"nullable":27,"default":88,"properties":89},"message","Human-readable status message; `\"success\"` on a successful call.","success",[],{"name":91,"required":18,"type":92,"description":93,"nullable":27,"properties":94},"server_time","string · date-time","Server-side timestamp when the response was produced, in ISO 8601 format (UTC).",[],{"data":96,"message":88,"server_time":102},{"gender":97,"language":98,"locale":99,"preview_audio_url":100,"voice_id":101},"female","english","en-US","https:\u002F\u002Fexample.com\u002Fclone.mp3","example_cloned_voice_id","2026-09-04T00:00:00Z",[104],{"name":88,"description":105,"summary":106,"value":107},"Examples illustrate the response structure, not live account data or a pricing quote. IDs and URLs are placeholders. Query model discovery and cost endpoints for current availability and prices.","Successful response",{"data":108,"message":88,"server_time":102},{"gender":97,"language":98,"locale":99,"preview_audio_url":100,"voice_id":101},[],{"status":111,"description":112,"contentType":23,"schema":113,"example":136,"headers":139},"default","Error response. All failures share one envelope: an `error` object with a numeric `code`, a human-readable `message`, an optional `details` string, and an optional `hint` giving an actionable next step (useful for AI agents).",{"type":114,"description":26,"nullable":27,"properties":115},"ErrorResponse",[116],{"name":117,"required":18,"type":118,"description":26,"nullable":27,"properties":119},"error","ErrorDetail",[120,125,129,133],{"name":121,"required":18,"type":122,"description":123,"nullable":27,"properties":124},"code","integer","Machine-readable error code. Mirrors the HTTP status for transport-level failures (e.g. 401, 404, 422, 500) and may carry a business-specific code otherwise.",[],{"name":126,"required":27,"type":31,"description":127,"nullable":18,"properties":128},"details","Optional structured detail about the failure, e.g. a JSON string of per-field validation errors on a 422. Absent when there is nothing extra to report.",[],{"name":130,"required":27,"type":31,"description":131,"nullable":18,"properties":132},"hint","Actionable next step for resolving the error, written for both humans and AI agents (e.g. how to fix the request, or where to obtain an API key). May be absent.",[],{"name":86,"required":18,"type":20,"description":134,"nullable":27,"properties":135},"Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.",[],{"error":137},{"code":138,"message":20,"details":20,"hint":20},1,[],[141],{"APIKeyHeader":142},[],[144,147,150],{"lang":145,"source":146},"SDK","from visionstory import VisionStoryClient\n\nclient = VisionStoryClient.from_env()\nvoice = client.clone_voice(\n    audio_url=\"https:\u002F\u002Fexample.com\u002Fmedia\u002Fvoice-sample.mp3\",\n    preview_text=\"Welcome to VisionStory.\",\n)\nprint(voice)",{"lang":148,"source":149},"REST","import os\nimport requests\nimport base64\n\ndef encode_base64(file_path):\n    with open(file_path, 'rb') as file:\n        encoded_string = base64.b64encode(file.read()).decode('utf-8')\n    return encoded_string\n\nheaders = {\"X-API-Key\": os.environ[\"VISIONSTORY_API_KEY\"]}\n\n# payload = {\n#     \"audio_url\": \"https:\u002F\u002Fstorage.googleapis.com\u002Feleven-public-prod\u002Fpremade\u002Fvoices\u002FXb7hH8MSUJpSbSDYk0k2\u002Fd10f7534-11f6-41fe-a012-2de1e482d336.mp3\",\n#     \"preview_text\": \"How are you doing guys, this is my voice\"\n# }\n\naudio_file_path = '\u002Fpath\u002Fto\u002Faudio.mp3'\npayload = {\n    \"inline_data\": {\n        \"mime_type\": \"audio\u002Fmp3\",\n        \"data\": encode_base64(audio_file_path)\n    },\n    \"preview_text\": \"How are you doing guys, this is my voice\"\n}\n\n# wait for about 15 seconds\nresponse = requests.post(\n    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvoice',  json=payload, headers=headers\n)\nresp_data = response.json()\nprint(resp_data['data']['voice_id'])",{"lang":151,"source":152},"cURL","curl -X 'POST' \\\n      'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvoice' \\\n      -H 'accept: application\u002Fjson' \\\n      -H 'content-type: application\u002Fjson' \\\n      -H 'X-API-Key: $VISIONSTORY_API_KEY' \\\n      --data '\n{\n    \"audio_url\": \"https:\u002F\u002Fstorage.googleapis.com\u002Feleven-public-prod\u002Fpremade\u002Fvoices\u002FXb7hH8MSUJpSbSDYk0k2\u002Fd10f7534-11f6-41fe-a012-2de1e482d336.mp3\",\n    \"preview_text\": \"How are you doing guys, this is my voice\"\n}\n'","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">from\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> visionstory \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">client \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> VisionStoryClient.from_env()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">voice \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> client.clone_voice(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    audio_url\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Fmedia\u002Fvoice-sample.mp3\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FFA657\">    preview_text\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"Welcome to VisionStory.\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(voice)\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>","\u003Cpre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">{\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"gender\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"female\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"language\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"english\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"locale\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"en-US\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"preview_audio_url\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"https:\u002F\u002Fexample.com\u002Fclone.mp3\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">    \"voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"example_cloned_voice_id\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">  },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"message\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"success\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#7EE787\">  \"server_time\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"2026-09-04T00:00:00Z\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1790231924485]