Zoice For Developers | Zoice API

Create Voice Profile API Docs

POST /v1/voice-profiles is the API helper endpoint to create a new voice profile on Zoice Dev. Voice profiles are useful for ensuring brand consistency and for reusing a character voice across multiple AI avatar videos. Once created, you can reuse the voice profile as inputs for various models for AI media generation. The voices generated with this endpoint are marked as private for the voice_type field in the metadata.

API Request

This endpoint handles the task asynchronously using a fast queue-based system, and the request immediately returns a request_id. Use the request_id to poll the status of the voice generation and return the result after the task is completed.

Sending Request

bash

curl -X POST "https://api.zoice.com/v1/voice-profiles" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOICE_API_KEY" \
  -d '{
    "voice_name": "Sophia",
    "reference_audio_urls": [
      "https://storage.zoice.com/api/assets/audio-ddc61733-0ed9-...mp3"
    ],
    "gender": "female",
    "age": "early-middle-aged",
    "language": "en",
    "accent": "en-american",
    "description": "early middle aged woman"
  }'

Response Format

json

{
  "request_id": 'd1f47b9c-6387-49d0-a403-...',
  "status": 'processing',
}

Polling and Output

After submitting an asynchronous API request, you can use the request_id obtained from the response to further poll for the status of the generation and ultimately retrieve the result after the completion. Use the /v1/fetch/request_id endpoint to perform this operation.

Polling Request

typescript

curl -X GET "https://api.zoice.com/v1/fetch/{request_id}" \
  -H "Authorization: Bearer $ZOICE_API_KEY"

Polling Response

typescript

{
  "status": "success",
  "request_id": "27f96f9d-8b3b-4",
  "type": "voice_profile",
  "output":
    {
	  "credits": 500,
      "voice_id": "bedf6a57-c6a5-47c0-ab16-58bf6fb30803",
      "voice_name": "Sophia",
      "description": "early middle aged woman",
      "age": "early-middle-aged",
      "gender": "female",
      "language": "en",
      "accent": "en-american",
      "generation_info":
        {
          "reference_audio_urls":
            [
              "https://storage.zoice.com/api/assets/audio-ddc61733-0ed9-...mp3",
            ],
        },
	  "voice_type": "private",
	  "voice_state": "active",
      "preview_url": "https://storage.zoice.com/api/assets/audio-c018ff3d-691f-.mp3",
	  "created_at": "2026-07-18T15:20:20.224Z"
    }
}

Schema

Input

Parameter	Type	Required	Default	Range	Description
voice_name	string	Yes	-	-	Name of the voice profile
reference_audio_urls	string[]	Yes	-	-	Array of reference audio urls to be used for generation of voice profile
gender	string	No	-	"male", "female", "neutral"	The gender for the voice profile
age	string	No	-	"child", "teen", "young-adult", "early-middle-aged", "late-middle-aged", "senior"	The age for the voice profile
language	string	No	-	"af", "ar", "hy", "as", "ast", "az", "be", "bn", "bs", "bg", "yue", "ca", "ceb", "ny", "zh", "hr", "cs", "da", "nl", "en", "et", "fil", "fi", "fr", "gl", "ka", "de", "el", "gu", "ha", "he", "hi", "hu", "is", "id", "ga", "it", "ja", "jv", "kn", "kk", "ky", "ko", "lv", "ln", "lt", "lb", "mk", "ms", "ml", "mt", "mi", "mr", "mn", "ne", "no", "oc", "or", "ps", "fa", "pl", "pt", "pa", "ro", "ru", "sr", "sd", "sk", "sl", "so", "es", "sw", "sv", "tg", "ta", "te", "th", "tr", "uk", "ur", "uz", "vi", "cy"	The language for the voice profile
accent	string	No	-	"af-standard", "ar-modern-standard", "ar-egyptian", "ar-gulf", "ar-levantine", "ar-bahraini", "ar-kuwaiti", "ar-omani", "ar-qatari", "ar-saudi", "ar-iraqi", "ar-jordanian", "ar-palestinian", "ar-syrian", "ar-algerian", "ar-moroccan", "ar-tunisian", "ar-libyan", "ar-sudanese", "hy-standard", "as-standard", "az-standard", "be-standard", "bn-standard", "bs-standard", "bg-bansko", "bg-rhodopean", "bg-ruse", "bg-sofia", "bg-standard", "bg-varna", "ca-standard", "ceb-standard", "ny-standard", "zh-guangzhou-cantonese", "zh-hong-kong-cantonese", "zh-singapore-cantonese", "zh-beijing-mandarin", "zh-singapore-mandarin", "zh-taiwan-mandarin", "zh-standard", "hr-dubrovnik", "hr-istrian", "hr-standard", "hr-zagreb", "cs-moravian", "cs-prague", "cs-silesian", "cs-standard", "da-copenhagen", "da-jutlandic", "da-standard", "da-zealandic", "nl-brabantian", "nl-flemish", "nl-gronings", "nl-limburgish", "nl-standard", "en-american", "en-australian", "en-british", "en-canadian", "en-indian", "en-irish", "en-jamaican", "en-new-zealand", "en-nigerian", "en-scottish", "en-south-african", "en-african-american", "en-singaporean", "en-boston", "en-chicago", "en-new-york", "en-us-southern", "en-us-midwest", "en-us-northeast", "en-cockney", "en-geordie", "en-received-pronunciation", "en-scouse", "en-welsh", "en-yorkshire", "en-arabic", "en-bulgarian", "en-chinese", "en-croatian", "en-czech", "en-danish", "en-dutch", "en-filipino", "en-finnish", "en-french", "en-german", "en-greek", "en-hindi", "en-indonesian", "en-italian", "en-japanese", "en-korean", "en-malay", "en-polish", "en-portuguese", "en-romanian", "en-russian", "en-slovak", "en-spanish", "en-swedish", "en-tamil", "en-turkish", "en-ukrainian", "et-standard", "fil-cebuano", "fil-ilocano", "fil-standard", "fi-eastern", "fi-helsinki", "fi-standard", "fi-tampere", "fi-turku", "fi-western", "fr-acadian", "fr-african", "fr-belgian", "fr-cajun", "fr-creole", "fr-meridional", "fr-parisian", "fr-quebec", "fr-standard", "fr-swiss", "gl-standard", "ka-standard", "de-bavarian", "de-berlinerisch", "de-rhine-franconian", "de-saxon", "de-standard", "de-swabian", "el-aegean", "el-athenian", "el-cretan", "el-cypriot", "el-macedonian", "el-pontic", "el-standard", "gu-standard", "ha-standard", "he-standard", "hi-awadhi", "hi-bengali", "hi-bhojpuri", "hi-bihari", "hi-chhattisgarhi", "hi-gujarati", "hi-haryanvi", "hi-khariboli", "hi-malvi", "hi-marathi", "hi-marwadi", "hi-punjabi", "hi-rajasthani", "hi-standard", "hi-tamil", "hi-telugu", "hu-standard", "hu-budapest", "hu-eastern", "hu-western", "hu-northern", "hu-southern", "is-standard", "id-balinese", "id-javanese", "id-standard", "id-sundanese", "ga-standard", "it-calabrese", "it-florentine", "it-genoese", "it-milanese", "it-neapolitan", "it-romanesco", "it-sicilian", "it-standard", "it-ticinese", "it-tuscan", "it-venetian", "ja-kansai", "ja-kanto", "ja-kyushu", "ja-okinawa", "ja-standard", "ja-tohoku", "jv-standard", "kn-standard", "kk-standard", "ky-standard", "ko-chungcheong", "ko-gyeongsang", "ko-hamgyong", "ko-jeolla", "ko-seoul", "ko-standard", "lv-standard", "ln-standard", "lt-standard", "lb-standard", "mk-standard", "ms-brunei", "ms-indonesian", "ms-kelantanese", "ms-malaysian", "ms-singaporean", "ms-standard", "ml-standard", "mr-standard", "ne-standard", "no-standard", "no-oslo", "no-bergen", "no-trøndersk", "no-northern", "no-sørlandsk", "ps-standard", "fa-standard", "pl-kashubian", "pl-mazovian", "pl-podhale", "pl-silesian", "pl-standard", "pt-brazilian", "pt-european", "pt-african", "pt-azorean", "pt-creole", "pt-galician", "pt-madeiran", "pa-standard", "ro-banat", "ro-bucovina", "ro-maramures", "ro-moldovan", "ro-oltenia", "ro-standard", "ro-transylvanian", "ru-moscow", "ru-saint-petersburg", "ru-standard", "sr-standard", "sd-standard", "sk-central", "sk-eastern", "sk-standard", "sk-western", "sl-standard", "so-standard", "es-latin-american", "es-peninsular", "es-andalusian", "es-argentine", "es-basque", "es-canary-islands", "es-caribbean", "es-chilean", "es-colombian", "es-cuban", "es-dominican", "es-ecuadorian", "es-galician", "es-mexican", "es-peruvian", "es-puerto-rican", "es-venezuelan", "sw-standard", "sv-gothenburg", "sv-gotland", "sv-norrland", "sv-scanian", "sv-standard", "sv-stockholm", "ta-chennai", "ta-coimbatore", "ta-madurai", "ta-salem", "ta-standard", "ta-thanjavur", "ta-tirunelveli", "te-standard", "th-standard", "tr-aegean", "tr-anatolian", "tr-black-sea", "tr-central", "tr-eastern", "tr-istanbul", "tr-southeastern", "tr-standard", "uk-kiev", "uk-standard", "ur-standard", "vi-standard", "vi-northern", "vi-central", "vi-southern", "cy-standard"	The accent for the voice profile
description	string	No	-	-	Add a brief description
preview_text	string	No	-	10-200 characters	Short script to generate a preview of the voice profile

Output

Field	Type	Description
status	string	The status of the API request. Allowed values: `"success"`, `"processing"`, `"failed"`
request_id	string (uuid)	A unique identifier generated for tracking this specific request.
type	string	The type of media content generated. Allowed values: `"video"`, `"image"`, `"audio"`, `"voice_profile"`, `"avatar_profile"`
output	object	An object containing the generated media url and metadata.
output.credits	number	Credits used for generation.
output.voice_id	string (uuid)	The unique identifier for the generated voice profile.
output.voice_name	string	The name assigned to the voice profile.
output.description	string	A brief description of the voice's characteristics.
output.age	string	The age category of the voice (e.g., `"young-adult"`)
output.gender	string	The gender of the voice (e.g., `"male"`).
output.language	string	The primary language code for the voice profile (e.g., `"en"`).
output.accent	string	The specific accent regional variant (e.g., `"en-american"`).
output.voice_type	string	The type of the voice profile. Allowed values: `private`, `imported`, `public`
output.voice_state	string	The state of the voice profile. Allowed values: `processing`, `active`
output.preview_url	string (url)	The direct URL to an audio sample file for previewing the generated voice.
output.generation_info	object	The object containing the information regarding voice profile generation.
output.generation_info.reference_audio_urls	string[]	String array including the URLs to the input audio used for generating the audio profile.
output.generation_info.preview_text	string	Custom text used for the generation of preview_url audio, if provided.
output.created_at	string	Date and time of creation in UTC format.