API de texto a voz

Esta página trata dos familias de modelos de voz. MiniMax Speech 2.8 pertenece a su propio grupo, MiniMax Speech oficial, y es la que describen por defecto las secciones siguientes. La voz de Doubao de ByteDance (seed-tts-2.0, seed-audio-1.0) pertenece a otro grupo y solo usa el endpoint compatible con OpenAI; vea Voz de Doubao. La clonación de voz con seed-icl-2.0, del mismo grupo, se explica en Clonación de voz de Doubao. Una clave solo llega a estos modelos si incluye el grupo correspondiente; puede añadir el grupo a una clave de chat o video existente en lugar de crear una nueva.

Sintetizar voz

Ambos endpoints devuelven el clip completo de forma síncrona. Use el endpoint compatible con OpenAI para trabajar directamente con los SDK de OpenAI, y el nativo para el conjunto completo de parámetros y el streaming.

MiniMax Speech 2.8 convierte texto en audio de forma síncrona: la respuesta es el propio audio, sin ninguna tarea que consultar. Usa la misma Base URL (vea la tabla al inicio de la página) y la misma autenticación Bearer que el resto de modelos; no hay un host ni una credencial de audio aparte.

Los ID distinguen mayúsculas y minúsculas y no tienen alias; tts-1 / tts-1-hd no se reconocen. Use una clave con este grupo habilitado y confirme los ID con GET /v1/models.

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-turbo",
    "input": "Hola, mundo.",
    "voice": "English_expressive_narrator",
    "response_format": "mp3"
  }' \
  --output hola.mp3

Endpoint compatible con OpenAI

POST /v1/audio/speech acepta la estructura de solicitud de OpenAI y responde con los bytes de audio sin envolver. Los campos también están en la referencia de la API.

• Sin voice, el texto con caracteres chinos usa Chinese (Mandarin)_News_Anchor; el resto usa English_expressive_narrator.
• Los nombres de voz de OpenAI usan la misma voz predeterminada.
• Un speed dentro del rango se ajusta a 0.5-2.
• stream_format no es compatible y devuelve 400.

Con los SDK oficiales de openai solo cambian la Base URL y los valores de model / voice:

from openai import OpenAI

client = OpenAI(base_url="https://api.hop-base.com/v1", api_key="sk-tu-clave")

response = client.audio.speech.create(
    model="speech-2.8-turbo",
    voice="English_expressive_narrator",
    input="Hola, mundo.",
    response_format="mp3",
)
response.write_to_file("hola.mp3")

# Texto largo: escriba los bytes en disco a medida que llegan
# en lugar de acumular todo el clip
with client.audio.speech.with_streaming_response.create(
    model="speech-2.8-turbo",
    voice="English_expressive_narrator",
    input="Aquí va un guion más largo.",
) as streamed:
    streamed.stream_to_file("largo.mp3")

Endpoint nativo

POST /v1/t2a_v2 toma el cuerpo de solicitud T2A v2 de MiniMax tal cual, y los campos que la pasarela no conoce se reenvían sin cambios. La respuesta JSON también sigue la estructura oficial, salvo los errores.

data.audio es el audio codificado en hexadecimal y extra_info incluye usage_characters y los metadatos del audio. stream: true cambia a SSE; vea Streaming.

import requests

resp = requests.post(
    "https://api.hop-base.com/v1/t2a_v2",
    headers={"Authorization": "Bearer sk-tu-clave"},
    json={
        "model": "speech-2.8-hd",
        "text": "你好，世界",
        "voice_setting": {"voice_id": "Chinese (Mandarin)_News_Anchor", "speed": 1.0},
        "audio_setting": {"format": "mp3", "sample_rate": 32000},
    },
)
body = resp.json()
open("hola.mp3", "wb").write(bytes.fromhex(body["data"]["audio"]))
print(body["extra_info"]["usage_characters"])  # caracteres facturados

En el endpoint nativo la pasarela solo hace tres cosas:

• Valida model, la longitud de text, stream y output_format.
• Ajusta voice_setting.speed al rango oficial.
• Limita el cuerpo a 1 MiB.

El resto se reenvía tal cual, y un valor fuera del rango oficial lo rechaza el servicio con 400. Los valores y predeterminados de las tablas siguientes son los oficiales.

(laughs) (chuckle) (coughs) (clear-throat) (groans) (breath) (pant) (inhale) (exhale) (gasps)
(sniffs) (sighs) (snorts) (burps) (lip-smacking) (humming) (hissing) (emm) (sneezes)

Voces del sistema

Todas las voces de la lista oficial de voces del sistema de MiniMax — 332 voces en 24 idiomas — funcionan aquí; pase el voice_id exactamente como aparece allí. La tabla siguiente es solo una selección inicial.

Use la columna voice_id tal cual: mayúsculas, espacios y paréntesis incluidos. Nombre es la etiqueta oficial.

• Las voces en cantonés necesitan language_boost: "Chinese,Yue".
• Use una voz en mandarín para texto en chino.
• Verificado el 2026-09-16: solo fallan dos voces de la lista oficial; el servicio las rechaza con "voice id not exist".
• Son Cantonese_ProfessionalHost (F) y Cantonese_ProfessionalHost (M).
• POST /v1/get_voice con {"voice_type": "system"} devuelve la lista de voces del sistema.

Streaming

En el endpoint nativo, stream: true cambia la respuesta a SSE. Cada evento data: {...} lleva un fragmento de audio en hexadecimal, y el evento final tiene data.status 2 más extra_info. Lea el cuerpo línea a línea, decodifique el fragmento de cada evento y añádalo al archivo.

import json
import requests

with requests.post(
    "https://api.hop-base.com/v1/t2a_v2",
    headers={"Authorization": "Bearer sk-tu-clave"},
    json={
        "model": "speech-2.8-turbo",
        "text": "Aquí va un guion más largo.",
        "stream": True,
        "stream_options": {"exclude_aggregated_audio": True},
        "voice_setting": {"voice_id": "Spanish_SereneWoman"},
        "audio_setting": {"format": "mp3", "sample_rate": 32000},
    },
    stream=True,
    timeout=(10, 300),
) as resp, open("largo.mp3", "wb") as out:
    resp.raise_for_status()
    for line in resp.iter_lines():
        if not line.startswith(b"data:"):
            continue
        event = json.loads(line[5:])
        base = event.get("base_resp") or {}
        if base.get("status_code", 0) != 0:  # fallo a mitad: no se factura y el stream termina
            raise RuntimeError(base.get("status_msg"))
        data = event.get("data") or {}
        if data.get("audio"):
            out.write(bytes.fromhex(data["audio"]))
        if data.get("status") == 2:
            print(event["extra_info"]["usage_characters"])  # caracteres facturados

Latencia y tiempos de espera

Medido con texto corto (una o dos frases): los endpoints síncronos devuelven el clip completo en unos 1.5-2.4 s, y con stream: true el primer fragmento de audio llega en aproximadamente 1 s.

La latencia crece con la longitud del texto, así que use streaming para todo lo largo (MiniMax recomienda streaming a partir de 3000 caracteres). Para las solicitudes síncronas, siga la misma pauta de cliente que los demás endpoints síncronos en Concurrencia, tiempos de espera y facturación: un tiempo de lectura de 300 s o más.

Clonación de voz

Clone una voz a partir de su propia grabación y úsela en ambos endpoints como una voz del sistema. El flujo replica la API oficial de clonación de voz de MiniMax, así que el código de los SDK oficiales funciona cambiando la Base URL y la clave. El grupo de la clave debe incluir los modelos de MiniMax Speech.

1. Suba el audio

POST /v1/files/upload recibe multipart/form-data con exactamente estos dos campos; cualquier otro devuelve 400.

• voice_clone es la grabación a clonar; prompt_audio es un fragmento de ejemplo opcional.
• Duración: voice_clone de 10 s a 5 min, prompt_audio menos de 8 s.
• La duración se valida al clonar.

curl https://api.hop-base.com/v1/files/upload \
  -H "Authorization: Bearer sk-your-key" \
  -F purpose=voice_clone \
  -F file=@my_voice.mp3
# → {"file":{"file_id":123456789,"bytes":…,"created_at":…,"filename":"my_voice.mp3","purpose":"voice_clone"},"base_resp":{…}}

2. Clone la voz

POST /v1/voice_clone recibe el file_id y un voice_id que usted elige. Añada text y model para obtener una vista previa.

curl https://api.hop-base.com/v1/voice_clone \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyNarrator01",
    "text": "Hello, this is my cloned voice.",
    "model": "speech-2.8-hd",
    "need_noise_reduction": true
  }'
# respuesta: input_sensitive, input_sensitive_type, demo_audio (enlace de descarga de la vista previa en api.hop-base.com, válido 24 horas; vacío sin text), extra_info.usage_characters (caracteres facturados de la vista previa), base_resp

• voice_id usa letras, dígitos, - y _; empieza por letra y no termina en - ni _.
• clone_prompt es {"prompt_audio": <file_id>, "prompt_text": "…"}, y ambas claves son obligatorias.
• prompt_text es la transcripción exacta del fragmento, terminada en puntuación.

Use la voz clonada

Pase su voice_id como voice en /v1/audio/speech, o como voice_setting.voice_id (también timber_weights[].voice_id) en /v1/t2a_v2.

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "speech-2.8-turbo", "input": "Hello again.", "voice": "MyNarrator01"}' \
  --output cloned.mp3

Ciclo de vida

• Los archivos subidos son de un solo uso: una clonación correcta elimina el archivo de origen y el de ejemplo, así que vuelva a subirlos para clonar otra vez.
• Si la clonación falla, los archivos se conservan para reintentar.
• Los archivos sin usar se eliminan 24 horas después de subirlos. Eliminar un archivo nunca afecta a las voces ya clonadas.
• Una voz que no se usa para sintetizar en los 7 días siguientes a la clonación se elimina, y no se cobra tarifa de clonación por ella.
• Las voces son privadas de su cuenta (en una cuenta de empresa, las comparten las claves de los miembros del titular); otras cuentas no pueden usarlas aunque conozcan el voice_id.

# Lista sus voces clonadas ("system" = voces del sistema, "all" = ambas; "voice_generation" siempre está vacío)
curl https://api.hop-base.com/v1/get_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"voice_type": "voice_cloning"}'
# Elimina una voz clonada
curl https://api.hop-base.com/v1/delete_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"voice_type": "voice_cloning", "voice_id": "MyNarrator01"}'
# Archivos subidos aún sin usar: listar, consultar, eliminar
curl "https://api.hop-base.com/v1/files/list?purpose=voice_clone" -H "Authorization: Bearer sk-your-key"
curl "https://api.hop-base.com/v1/files/retrieve?file_id=123456789" -H "Authorization: Bearer sk-your-key"
curl https://api.hop-base.com/v1/files/delete \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"file_id": 123456789, "purpose": "voice_clone"}'

Facturación

La voz se factura por carácter facturado. El recuento autoritativo es extra_info.usage_characters en la respuesta nativa; el endpoint compatible con OpenAI solo devuelve audio, así que consulte la misma cifra como tts_characters en el registro de uso de la consola.

Cada carácter Unicode cuenta 1, y cada carácter chino (CJK) cuenta 1 más, de modo que un carácter chino cuenta 2. La puntuación, los espacios, los emoji y las marcas de pausa como <#0.5#> cuentan 1 cada uno.

• Hello, world. → 13 caracteres facturados
• 你好，世界 → 5 caracteres, 4 de ellos chinos → 9 caracteres facturados

Una solicitud rechazada con 400 o que falla durante la síntesis no se factura, y un stream que termina antes del evento final tampoco. Los precios de lista oficiales por millón de caracteres están en la página de precios; la tarifa de su grupo aparece en el catálogo de modelos con la sesión iniciada.

Tarifa de clonación

Subir y clonar es gratis. La tarifa de clonación se cobra una sola vez, con la primera síntesis correcta de la voz, y aparece como un concepto adicional voice_clone_activation en el registro de uso de esa síntesis.

El text de vista previa se factura solo como caracteres de voz y no cuenta como primer uso; las solicitudes fallidas no se facturan. La tarifa figura en la página de precios.

Errores y recomendaciones

En ambos endpoints los errores son un estado distinto de 200 con {"error":{…}}, no base_resp. Las validaciones propias del gateway (modelo, texto, formato, velocidad, campos desconocidos) no llevan code; guíese por message.

Los 400 de clonación cubren un file_id usado o caducado, un voice_id ya ocupado, una duración del audio fuera de rango o una verificación de text_validation fallida. Mensajes habituales y cómo actuar:

400 voice id not exist                       ID de voz desconocido, o voz clonada eliminada / caducada
400 file_id ... does not exist; uploaded files are single-use and expire 24 hours after upload    vuelva a subir el audio
400 voice_id ... already exists             elija otro nombre o elimine la voz anterior
400 (clonación) duración del audio fuera de rango    origen de 10 s a 5 min, ejemplo de menos de 8 s
400 (clonación) falla del reconocimiento de voz      solo con text_validation: corrija la transcripción o baje accuracy
503 voice cloning is temporarily unavailable    reintente más tarde
400 sensitive content / >10% invalid chars   reescriba o limpie el texto
400 invalid request parameters; check text, voice_setting and audio_setting (opus requires an explicit sample_rate)
413 request body exceeds the 1048576 byte limit (got N bytes)            cuerpo de más de 1 MiB
502 response_size_limit_exceeded (audio over 64 MiB)    use stream: true, texto más corto o menor bitrate
stream que falla a mitad: un último evento data: {"base_resp":{...}} y se cierra; no se factura

Voz de Doubao

Los dos modelos de voz Doubao de ByteDance pertenecen a su propio grupo, Doubao Voz en la nube. Una clave solo llega a ellos si incluye este grupo; puede añadirlo a una clave existente. Solo usan el endpoint compatible con OpenAI POST /v1/audio/speech, devuelven el clip completo de forma síncrona y no admiten streaming. El endpoint nativo /v1/t2a_v2 no admite estos dos modelos y devuelve 400 indicando que use /v1/audio/speech.

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-tts-2.0",
    "input": "你好，欢迎使用豆包语音合成。",
    "voice": "zh_female_vv_uranus_bigtts"
  }' \
  -o out.mp3

Con el SDK oficial openai, solo cambie la Base URL y los valores de model / voice. Con seed-audio-1.0, escriba la escena y los diálogos en input:

from openai import OpenAI

client = OpenAI(base_url="https://api.hop-base.com/v1", api_key="sk-your-key")

response = client.audio.speech.create(
    model="seed-tts-2.0",
    voice="en_female_dacey_uranus_bigtts",
    input="Hola, bienvenido a la síntesis de voz de Doubao.",
)
response.write_to_file("out.mp3")

# Audio de escena: escriba "descripción de la escena + diálogos" en input; tarda unos 10-30 s
scene = client.audio.speech.create(
    model="seed-audio-1.0",
    voice="alloy",  # el SDK exige voice; un nombre de voz de OpenAI equivale a no indicarla y la voz la decide la descripción
    input="先是一声手机震动的声音，随后一名男子（中青年，嗓音低沉）用严肃语气说道：“钟sir，你是什么时候被收买的？”",
    timeout=300,
)
scene.write_to_file("scene.mp3")

Parámetros de voz de Doubao

• seed-tts-2.0: sin voice, o con un nombre de voz estándar de OpenAI como alloy, la voz por defecto depende del idioma del texto: zh_female_vv_uranus_bigtts para chino y en_female_dacey_uranus_bigtts para los demás idiomas. Puede elegir otras voces 2.0 (ID terminados en _uranus_bigtts, como zh_male_m191_uranus_bigtts).
• seed-audio-1.0: escriba "descripción de la escena + diálogos" en input, como en el ejemplo de arriba. Sin voice, o con un nombre de voz estándar de OpenAI, la voz la decide la descripción; también puede indicar un ID de voz de Doubao. Si la descripción es demasiado larga, el audio que pide puede superar la duración máxima del modelo y la solicitud devuelve 400 duration_out_of_range; acórtela y vuelva a enviarla.
• Salida: seed-tts-2.0 es mono a 24 kHz (pcm son datos sin procesar mono de 16 bits a 24 kHz, igual que en OpenAI); seed-audio-1.0 es estéreo a 48 kHz.
• No admite streaming; stream_format devuelve 400. Si la voz no coincide con el idioma del texto (por ejemplo, una voz inglesa leyendo texto solo en chino) y no se genera audio, la solicitud devuelve 400 no_audio.
• Para textos más largos, divídalos en el cliente dentro del límite, pida cada fragmento y una el audio.

Tiempos y facturación

• seed-tts-2.0: unos 1-3 s para una frase corta y unos 70 s para 2.000 caracteres.
• seed-audio-1.0: unos 10-30 s.
• Ambos responden cuando el clip completo está generado. Configure el tiempo de lectura del cliente como en los demás endpoints síncronos de Concurrencia, tiempos de espera y facturación: al menos 300 segundos.
• seed-tts-2.0 se factura por caracteres de entrada y seed-audio-1.0 por la duración del audio generado; los precios oficiales están en la tabla de modelos de arriba y la tarifa real de su grupo aparece en el catálogo de modelos con la sesión iniciada. Las solicitudes rechazadas con 400 o que fallan durante la generación no se facturan.

Cualquier valor fuera de la tabla anterior devuelve 400; corrija la solicitud según el error en lugar de reintentarla sin cambios. Llamar a /v1/t2a_v2 también devuelve 400. 402, 404, 429 y 503 significan lo mismo que en Errores y recomendaciones, más arriba.

Clonación de voz de Doubao

Clone una voz propia a partir de una grabación suya y sintetice voz con ella. El modelo es seed-icl-2.0 (Doubao Voice Cloning 2.0). Está en el mismo grupo que la voz de Doubao, Doubao Voz en la nube, y una clave solo llega a él si incluye este grupo. Son tres pasos: envíe la grabación a POST /v1/voice_clone para obtener un voice_id (empieza por hbv_), páselo como voice a POST /v1/audio/speech y, cuando ya no lo necesite, consúltelo o elimínelo.

El formato de la solicitud es distinto al de la clonación de voz de MiniMax de arriba: la grabación va directamente en el JSON como base64, sin subir antes un archivo, y los tres endpoints de clonación exigen "model": "seed-icl-2.0" en el cuerpo. Si usa la clonación de voz de MiniMax y la de Doubao a la vez, use una clave distinta para cada una.

Cupo durante la fase de prueba: Durante la fase de prueba, cada cuenta puede conservar una voz clonada. Para cambiar de voz, elimine la anterior y vuelva a clonar, o reentrénela enviando su voice_id. El cupo de voces clonadas es limitado; cuando está lleno, la solicitud devuelve 503 voice_capacity_full, así que vuelva a intentarlo más tarde.

1. Clone una voz

POST /v1/voice_clone recibe un cuerpo JSON de hasta 16 MiB.

• language admite zh, en, ja, es, id, pt, de, fr, ko, it, th, vi, ru, fil, ms, ar, es-mx, pt-br, pl, tr, sv.
• La clonación termina de forma síncrona: en nuestra prueba, una grabación de 17 segundos tardó unos 33 segundos. Configure el tiempo de lectura del cliente en 300 s o más.

# Ponga la grabación en el cuerpo de la solicitud como base64 (jq 1.6+)
jq -n --rawfile audio <(base64 < my_voice.wav | tr -d '\n') \
  '{model: "seed-icl-2.0", audio: $audio, language: "es", demo_text: "Hola, esta es mi voz clonada."}' > clone.json

curl https://api.hop-base.com/v1/voice_clone \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d @clone.json

{
  "voice_id": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4",
  "status": "ready",
  "language": "es",
  "remaining_trainings": 14,
  "created_at": 1792051200,
  "demo_audio": "<audio en base64>",
  "demo_audio_format": "wav"
}

2. Sintetice con la voz clonada

Llame a POST /v1/audio/speech con model igual a seed-icl-2.0 y voice igual a su voice_id. Todo lo demás (parámetros, formatos y límites) es igual que en seed-tts-2.0 (vea Parámetros de voz de Doubao): input de hasta 5.000 caracteres, response_format entre mp3 / opus / aac / wav / pcm, speed de 0,5 a 2,0, salida mono a 24 kHz, clip completo devuelto de forma síncrona y sin streaming.

curl https://api.hop-base.com/v1/audio/speech \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0", "input": "La reunión se ha movido a las tres de la tarde.", "voice": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4"}' \
  -o cloned.mp3

• seed-icl-2.0 solo funciona con una voz que usted haya clonado: si omite voice o envía una voz del sistema o un nombre de voz de OpenAI, devuelve 400 voice_required.
• Una voz clonada solo funciona con seed-icl-2.0; con cualquier otro modelo devuelve 400 unknown_voice.
• Las voces clonadas son privadas de su cuenta (en una cuenta de empresa, las comparten las claves de los miembros del titular); otras cuentas no pueden usarlas aunque conozcan el voice_id.

3. Consulte y elimine

Ambos endpoints son gratuitos y el cuerpo también necesita model.

# Liste sus voces clonadas (añada voice_id para consultar solo esa)
curl https://api.hop-base.com/v1/get_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0"}'
# → {"voices":[{"voice_id":"hbv_k3m9x2p7q8r4t6w1y5z0a2b4","status":"ready","language":"es","remaining_trainings":14,"created_at":1792051200}]}

# Elimine una voz clonada
curl https://api.hop-base.com/v1/delete_voice \
  -H "Authorization: Bearer sk-your-key" -H "Content-Type: application/json" \
  -d '{"model": "seed-icl-2.0", "voice_id": "hbv_k3m9x2p7q8r4t6w1y5z0a2b4"}'
# → {"voice_id":"hbv_k3m9x2p7q8r4t6w1y5z0a2b4","deleted":true}

Con voice_id, get_voice devuelve directamente el objeto de esa voz (los mismos campos que la respuesta de clonación, sin la muestra de audio). Tras eliminarla, ese voice_id ya no se puede usar y el cupo se libera de inmediato.

Facturación de la clonación de voz

• La síntesis con una voz clonada se factura por caracteres de entrada al precio oficial de ¥3 por 10.000 caracteres, igual que seed-tts-2.0.
• Muestra: demo_text se factura por caracteres al mismo precio.
• La clonación en sí, la consulta y la eliminación son gratuitas; por ahora no hay tarifa de clonación. Las solicitudes fallidas no se facturan.

La tarifa real de su grupo aparece en el catálogo de modelos con la sesión iniciada.

Errores de la clonación de voz

Los errores tienen el mismo formato que en los demás endpoints: un estado distinto de 200 más {"error":{"message","type","code"}}. Los errores de validación de parámetros no llevan code; guíese por el message.

Próximos pasos

• Modelos disponibles: todos los ID de modelo y su grupo
• Referencia de la API: Crear voz
• API de video MiniMax Hailuo H3
• Códigos de error y reintentos
• Concurrencia, tiempos de espera y facturación