[{"data":1,"prerenderedAt":124},["ShallowReactive",2],{"reference-detail-clone_voice_api_v1_voice_post":3,"developer-code-f63q1e":122,"developer-code-mfuhlk":123},{"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":112,"codeSamples":115},"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, used to detect image vs audio. Audio: ['audio\u002Favi', 'audio\u002Fmpeg', 'audio\u002Fmp3', 'audio\u002Fmp4', 'audio\u002Fm4a', 'audio\u002Fwav']; 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,83],{"status":56,"description":57,"contentType":23,"schema":58,"example":79},"200","Successful Response",{"type":59,"description":26,"nullable":27,"properties":60},"BaseSuccessResponse_CloneVoiceResponse_",[61,69,74],{"name":40,"required":18,"type":62,"description":63,"nullable":18,"properties":64},"CloneVoiceResponse | null","The endpoint payload. Its shape is specific to each endpoint (see that endpoint's response schema); null for operations that return no body, such as delete.",[65],{"name":66,"required":18,"type":20,"description":67,"nullable":27,"properties":68},"voice_id","Unique identifier of the cloned voice. Pass it as `voice_id` in a text script to speak with this voice.",[],{"name":70,"required":27,"type":20,"description":71,"nullable":27,"default":72,"properties":73},"message","Human-readable status message; `\"success\"` on a successful call.","success",[],{"name":75,"required":18,"type":76,"description":77,"nullable":27,"properties":78},"server_time","string · date-time","Server-side timestamp when the response was produced, in ISO 8601 format (UTC).",[],{"data":80,"server_time":82,"message":72},{"voice_id":81},"voice_123456","2026-08-24T08:00:00Z",{"status":84,"description":85,"contentType":23,"schema":86,"example":109},"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":87,"description":26,"nullable":27,"properties":88},"ErrorResponse",[89],{"name":90,"required":18,"type":91,"description":26,"nullable":27,"properties":92},"error","ErrorDetail",[93,98,102,106],{"name":94,"required":18,"type":95,"description":96,"nullable":27,"properties":97},"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":99,"required":27,"type":31,"description":100,"nullable":18,"properties":101},"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":103,"required":27,"type":31,"description":104,"nullable":18,"properties":105},"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":70,"required":18,"type":20,"description":107,"nullable":27,"properties":108},"Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.",[],{"error":110},{"code":111,"message":20,"details":20,"hint":20},1,[113],{"APIKeyHeader":114},[],[116,119],{"lang":117,"source":118},"Python","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":120,"source":121},"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\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> os\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">import\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> base64\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">def\u003C\u002Fspan>\u003Cspan style=\"color:#D2A8FF\"> encode_base64\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(file_path):\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">    with\u003C\u002Fspan>\u003Cspan style=\"color:#79C0FF\"> open\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(file_path, \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'rb'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">) \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">as\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\"> file\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">        encoded_string \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> base64.b64encode(\u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">file\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">.read()).decode(\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'utf-8'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#FF7B72\">    return\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> encoded_string\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">headers \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"X-API-Key\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: os.environ[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"VISIONSTORY_API_KEY\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">]}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\"># payload = {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\">#     \"audio_url\": \"https:\u002F\u002Fstorage.googleapis.com\u002Feleven-public-prod\u002Fpremade\u002Fvoices\u002FXb7hH8MSUJpSbSDYk0k2\u002Fd10f7534-11f6-41fe-a012-2de1e482d336.mp3\",\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\">#     \"preview_text\": \"How are you doing guys, this is my voice\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\"># }\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">audio_file_path \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\"> '\u002Fpath\u002Fto\u002Faudio.mp3'\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">payload \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"inline_data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: {\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"mime_type\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"audio\u002Fmp3\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">        \"data\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: encode_base64(audio_file_path)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">    },\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    \"preview_text\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"How are you doing guys, this is my voice\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#8B949E\"># wait for about 15 seconds\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">response \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> requests.post(\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#A5D6FF\">    'https:\u002F\u002Fopenapi.visionstory.ai\u002Fapi\u002Fv1\u002Fvoice'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">,  \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">json\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">payload, \u003C\u002Fspan>\u003Cspan style=\"color:#FFA657\">headers\u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">headers\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">)\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">resp_data \u003C\u002Fspan>\u003Cspan style=\"color:#FF7B72\">=\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\"> response.json()\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#79C0FF\">print\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">(resp_data[\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'data'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">][\u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">'voice_id'\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">])\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\">    \"voice_id\"\u003C\u002Fspan>\u003Cspan style=\"color:#E6EDF3\">: \u003C\u002Fspan>\u003Cspan style=\"color:#A5D6FF\">\"voice_123456\"\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\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-08-24T08:00:00Z\"\u003C\u002Fspan>\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>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"color:#E6EDF3\">}\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>",1788166855864]