Voz a texto

POST /v1/audio/transcriptions

Transcribe audio a texto. Compatible con la API de OpenAI Audio Transcriptions - el mismo endpoint sirve los modelos OpenAI Whisper / GPT-4o-transcribe y los modelos de Google Gemini, y el gateway enruta al upstream correcto según el ID del modelo. Acepta o bien un multipart/form-data (compatible con el SDK de OpenAI) o un cuerpo application/json con audio codificado en base64.

Cuerpo de la solicitud

Modelos compatibles

¿No sabes qué modelo elegir? Elige según lo que necesites

Diarization = define response_format=diarized_json para obtener segments[].speaker. Límite de subida predeterminado 25 MB (ver Formatos de audio).

Los modelos de Google pueden servirse a través de la API de Gemini o, con una clave de cuenta de servicio BYOK de Vertex, a través de Google Cloud Vertex AI. La disponibilidad depende de los canales habilitados para tu espacio de trabajo - llama a /v1/models para ver qué puedes usar.

Formatos de audio compatibles

• mp3
• wav
• ogg
• flac
• m4a

Para cargas multipart, el formato se infiere de la extensión del nombre de archivo. Para solicitudes base64 (JSON), establece input_audio.format explícitamente. Tamaño máximo de carga: 25 MB.

Formatos de respuesta

El valor response_format los valores aceptados dependen del modelo. json es el valor predeterminado para todos los modelos (devuelve { text, usage }); text devuelve la cadena de transcripción en bruto.

• whisper-1 - json, text, verbose_json
• gpt-4o-transcribe, gpt-4o-mini-transcribe - json, text
• chirp-3, chirp-2, seed-asr-bigmodel, qwen3-asr-flash, fun-asr-flash - json, text
• gpt-4o-transcribe-diarize, chirp-3, seed-asr-bigmodel, fun-asr, fun-asr-mtl - also diarized_json (segmentos etiquetados por hablante; ver más abajo)

verbose_json (marcas de tiempo de segmentos) es solo para whisper-1;

Diarización de hablantes

Define response_format=diarized_json para obtener segmentos etiquetados por hablante: la respuesta añade un arreglo segments donde cada entrada lleva una etiqueta speaker más marcas de tiempo start/end (en segundos). Compatible con gpt-4o-transcribe-diarize (OpenAI), chirp-3 (Google), seed-asr-bigmodel (BytePlus: la mejor relación calidad-precio para chino y grabaciones largas) y fun-asr / fun-asr-mtl (Alibaba: archivo de grabación sin conexión, acepta una URL o un archivo). Otros modelos ignoran diarized_json y devuelven texto plano; chirp-2 lo rechaza (usa chirp-3).

Las etiquetas de hablante son nativas del proveedor (p. ej., "0"/"1" para chirp-3 y seed-asr, "A"/"B" para gpt-4o-transcribe-diarize); identifican hablantes distintos, pero no son identidades reales estables. En gpt-4o-transcribe-diarize puedes pasar known_speaker_names para orientar el etiquetado.

# Chinese meeting, cheapest diarization (BytePlus seed-asr):
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-asr-bigmodel",
    "input_audio": { "url": "https://your-bucket/signed/meeting.wav", "language": "zh" },
    "response_format": "diarized_json"
  }'

# English / highest quality (Google chirp-3, <=60 s per request):
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=chirp-3 \
  -F file=@call.wav \
  -F response_format=diarized_json

Ejemplo de respuesta

{
  "task": "transcribe",
  "text": "喂 你好 我这边是客服 有什么可以帮您",
  "duration": 6.2,
  "segments": [
    { "id": 0, "start": 0.10, "end": 0.90, "speaker": "0", "text": "喂 你好" },
    { "id": 1, "start": 1.20, "end": 6.20, "speaker": "1", "text": "我这边是客服 有什么可以帮您" }
  ]
}

Solicitud de ejemplo (multipart)

curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=gpt-4o-transcribe \
  -F file=@meeting.mp3 \
  -F response_format=json \
  -F language=en

Solicitud de ejemplo (JSON base64)

POST /v1/audio/transcriptions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "model": "gpt-4o-transcribe",
  "input_audio": {
    "data": "UklGRiQAAABXQVZFZm10I...",
    "format": "wav"
  },
  "response_format": "json",
  "language": "en"
}

Ejemplo - ASR sin conexión (seed-asr-bigmodel)

seed-asr-bigmodel (ASR sin conexión internacional de BytePlus) acepta dos entradas mutuamente excluyentes: una input_audio.url accesible (recomendada - tu propia URL firmada de almacenamiento de objetos con tiempo limitado; el audio nunca toca nuestro almacenamiento), o una carga directa de file/bytes (la preparamos en un bucket privado y la eliminamos justo después de la transcripción). Limitaciones: sin streaming (stream=true devuelve 400); las cargas de file admiten hasta 25 MB (usa una URL para grabaciones más grandes); el procesamiento por solicitud está limitado a unos 20 minutos, así que divide los audios muy largos. Facturado por duración del audio ($0.002/min).

# ① Quick test - replace ONLY YOUR_API_KEY and run it (uses our hosted sample audio).
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seed-asr-bigmodel",
    "input_audio": {
      "url": "https://synthorai-asr-sample-360831509259.s3.us-west-1.amazonaws.com/seed-asr-sample.wav",
      "language": "zh"
    }
  }'
# → {"text":"..."}

# ② Your own audio file (<=25 MB) - replace key + file path.
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model=seed-asr-bigmodel \
  -F language=zh \
  -F file=@/path/to/your-audio.wav

# ③ Your own signed URL (recommended for large files / privacy) - replace key + URL.
curl https://synthorai.io/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seed-asr-bigmodel","input_audio":{"url":"https://your-bucket/signed/meeting.wav","language":"zh"}}'

Notas / detalles: (1) language es opcional - los valores comunes son zh (mandarín), yue-CN (cantonés), en-US; omítelo para detectarlo automáticamente. (2) Al usar input_audio.url, la URL debe ser accesible públicamente por el servicio de transcripción - una URL privada/interna/protegida por autenticación fallará; una URL firmada (pre-firmada) de almacenamiento de objetos con tiempo limitado es la forma recomendada. (3) La carga de file y la URL son mutuamente excluyentes; elige una. (4) El audio sin habla reconocible (silencio) devuelve 200 con una cadena vacía {"text":""}, no un error.

Ejemplo - SDK de OpenAI para Python

El endpoint es compatible con OpenAI, por lo que el SDK oficial de OpenAI funciona directamente al sobrescribir base_url. Funciona igual para whisper-1, gpt-4o-transcribe y cualquier modelo de transcripción Gemini - solo cambia model.

from openai import OpenAI

client = OpenAI(
    base_url="https://synthorai.io/v1",
    api_key="YOUR_API_KEY",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=f,
        language="en",
        # prompt="Synthorai, BYOK, transcribe",   # optional vocabulary hint
        response_format="json",
    )

print(result.text)
# Token-level usage on gpt-4o-*:
if getattr(result, "usage", None):
    print(result.usage)

Ejemplo - SDK de OpenAI para Node.js

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  baseURL: "https://synthorai.io/v1",
  apiKey: process.env.SYNTHORAI_API_KEY,
});

const result = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("meeting.mp3"),
  language: "en",
  response_format: "json",
});

console.log(result.text);

Streaming (SSE)

Establece stream=true en gpt-4o-transcribe, gpt-4o-mini-transcribe, o cualquier modelo de transcripción Gemini para recibir eventos incrementales a medida que se decodifica el audio. El Content-Type de la respuesta es text/event-stream y los eventos terminan con data: [DONE]. whisper-1 no admite streaming (devuelve 400 si stream=true).

Tipos de eventos que verás para gpt-4o-transcribe:

data: {"type":"transcript.text.delta","delta":"Hello "}

data: {"type":"transcript.text.delta","delta":"world."}

data: {"type":"transcript.text.done","text":"Hello world."}

data: {"type":"usage","usage":{"type":"tokens","input_tokens":689,"output_tokens":287,"total_tokens":976,"input_token_details":{"audio_tokens":689,"text_tokens":0,"cached_tokens":0}}}

data: [DONE]

El streaming de Gemini usa los mismos nombres de eventos SSE, y el gateway emite el mismo objeto canónico usage documentado en Ejemplo de respuesta - idéntico entre OpenAI y Gemini - de modo que el código del cliente sea portable entre providers. El evento final usage siempre lleva el input_token_details desglose completo para una facturación precisa a tarifa de audio.

Errores

Todos los errores siguen el envelope de OpenAI: { error: { message, type, code, param? } }. Casos comunes:

• 400 model_not_found - el modelo no tiene capacidad de transcripción en los channels de este espacio de trabajo.
• 400 byok_strict_no_key - el espacio de trabajo es BYOK estricto (byok_fallback_to_pool=false) y no tiene clave de vault para el proveedor resuelto.
• 400 content_policy_violation - el campo prompt activó una regla de guardrail (p. ej. fuga de clave BYOK).
• 402 quota_exceeded - el costo estimado supera el cupo restante del espacio de trabajo. BYOK está exento.
• 408 - el cuerpo de la solicitud no terminó de subirse dentro del tiempo de lectura del servidor. Común con audio grande en una conexión lenta; reintenta o envía un archivo más pequeño.
• 413 - el audio supera el límite de 25 MB.
• 502 upstream_error - fallo de red upstream o respuesta no-2xx del proveedor del modelo.

Ejemplo de respuesta

{
  "text": "Thanks for joining today's call. Let's get started.",
  "usage": {
    "type": "tokens",
    "input_tokens": 689,
    "output_tokens": 287,
    "total_tokens": 976,
    "input_token_details": {
      "audio_tokens": 689,
      "text_tokens": 0,
      "cached_tokens": 0
    }
  }
}