Voices/Clone voice

Clone voice

POST/api/v1/voice

Clone a voice from a clean audio sample (AVI/MP3/MP4/M4A/WAV, up to 30MB) and get a reusable voice_id. 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.

Headers

X-API-KeystringRequired

Your VisionStory API key (sk-vs-...), kept server-side. Create one at OpenApi (Pro plan and up).

Request body

audio_urlstring | nullOptional

Publicly reachable URL of a clean voice sample. Provide either this or inline_data. Formats: AVI/MP3/MP4/M4A/WAV, up to 30MB.

inline_dataInlineDataModel | nullOptional

Voice sample as inline base64 data. Provide either this or audio_url.

Show 2 propertiesHide 2 properties

mime_typestringRequired

MIME type of the inline data; the gateway uses it to tell image / audio / video apart. The accepted set depends on the endpoint — see the field carrying this object. Talking video accepts audio ['audio/avi', 'audio/mpeg', 'audio/mp3', 'audio/mp4', 'audio/m4a', 'audio/wav'] and images ['image/jpeg', 'image/jpg', 'image/png', 'image/webp', 'image/heic'].

datastringRequired

The file's raw bytes encoded as a base64 string (no data: URI prefix).

preview_textstring | nullOptional

Text spoken in the generated preview clip for the cloned voice. Defaults to a built-in phrase. Max 100 characters.

Response

200Successful Response

Successful calls return a standard envelope: the endpoint payload under data (its fields are documented below), plus a message string ("success") and an ISO 8601 server_time.

Response fields (data)

voice_idstringRequired

Unique identifier of the cloned voice. Pass it as voice_id in a text script to speak with this voice.

localestringOptionalDefault ""

BCP 47 locale detected for the clone (e.g. en-US), same vocabulary as the locale field of GET /api/v1/voices and the locale parameter of POST /api/v1/tts; empty if detection was unavailable.

languagestringOptionalDefault ""

Primary language detected from the audio sample, e.g. english; empty if detection is still pending.

genderstringOptionalDefault ""

Voice gender detected from the audio sample; empty if detection is still pending.

preview_audio_urlstringOptionalDefault ""

URL of a short sample clip synthesized with the cloned voice; empty if not ready yet.

Errors

All error responses share one JSON 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 (handy for AI agents).

errorErrorDetailRequired

Error payload returned with every non-2xx response. Present only on failure; successful calls use the standard success envelope instead.

Show 4 propertiesHide 4 properties

codeintegerRequired

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.

messagestringRequired

Human-readable explanation of what went wrong. Safe to log or surface to end users; not localized.

detailsstring | nullOptional

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.

hintstring | nullOptional

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.

Request

curl -X POST 'https://openapi.visionstory.ai/api/v1/voice' \
  -H 'X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "audio_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  },
  "preview_text": "string"
}'

import requests

url = "https://openapi.visionstory.ai/api/v1/voice"
headers = {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
}
payload = {
  "audio_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  },
  "preview_text": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://openapi.visionstory.ai/api/v1/voice", {
  method: "POST",
  headers: {
    "X-API-Key": "sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": {
      "mime_type": "string",
      "data": "string"
    },
    "preview_text": "string"
  }),
});
const data = await response.json();
console.log(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "audio_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  },
  "preview_text": "string"
}`)
	req, _ := http.NewRequest("POST", "https://openapi.visionstory.ai/api/v1/voice", bytes.NewBuffer(payload))
	req.Header.Set("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://openapi.visionstory.ai/api/v1/voice"))
    .header("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
        {
          "audio_url": "https://cdn.visionstory.ai/example.png",
          "inline_data": {
            "mime_type": "string",
            "data": "string"
          },
          "preview_text": "string"
        }"""))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

<?php
$ch = curl_init("https://openapi.visionstory.ai/api/v1/voice");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "X-API-Key: sk-vs-xxxxxxxxxxxxxxxxxxx",
    "Content-Type: application/json",
]);
$payload = <<<'JSON'
{
  "audio_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  },
  "preview_text": "string"
}
JSON;
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

require "net/http"
require "uri"

uri = URI("https://openapi.visionstory.ai/api/v1/voice")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request["X-API-Key"] = "sk-vs-xxxxxxxxxxxxxxxxxxx"
request["Content-Type"] = "application/json"
request.body = <<~JSON
  {
    "audio_url": "https://cdn.visionstory.ai/example.png",
    "inline_data": {
      "mime_type": "string",
      "data": "string"
    },
    "preview_text": "string"
  }
  JSON
response = http.request(request)
puts response.body

import Foundation

var request = URLRequest(url: URL(string: "https://openapi.visionstory.ai/api/v1/voice")!)
request.httpMethod = "POST"
request.setValue("sk-vs-xxxxxxxxxxxxxxxxxxx", forHTTPHeaderField: "X-API-Key")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
request.httpBody = """
{
  "audio_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  },
  "preview_text": "string"
}
""".data(using: .utf8)
let (data, _) = try await URLSession.shared.data(for: request)
print(String(data: data, encoding: .utf8) ?? "")

using System;
using System.Net.Http;
using System.Text;

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://openapi.visionstory.ai/api/v1/voice");
request.Headers.Add("X-API-Key", "sk-vs-xxxxxxxxxxxxxxxxxxx");
var payload = """
{
  "audio_url": "https://cdn.visionstory.ai/example.png",
  "inline_data": {
    "mime_type": "string",
    "data": "string"
  },
  "preview_text": "string"
}
""";
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Response

200

{
  "data": {
    "voice_id": "example_cloned_voice_id",
    "locale": "en-US",
    "language": "english",
    "gender": "female",
    "preview_audio_url": "https://example.com/clone.mp3"
  },
  "message": "success",
  "server_time": "2026-09-04T00:00:00Z"
}