> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# API de reconocimiento de voz de OpenAI (/v1/audio/transcriptions)

> OpenAI generation API guide - Ace Data Cloud

Transcribe audio a texto, **totalmente compatible con el `/v1/audio/transcriptions` de OpenAI**. Cualquier SDK de OpenAI solo necesita apuntar `base_url` a `https://api.acedata.cloud` y cambiar la clave por tu AceData Token para usarlo directamente. Soporta respuestas completas y también la transcripción incremental SSE de `gpt-transcribe`.

* **URL de solicitud**: `POST https://api.acedata.cloud/v1/audio/transcriptions` (alias `POST /openai/audio/transcriptions`)
* **Autenticación**: encabezado de solicitud `Authorization: Bearer {token}`
* **Formato de solicitud**: `multipart/form-data`
* **Facturación**: se cobra según la duración del audio (ver tabla a continuación), menos de 1 segundo se cobra como 1 segundo.

## Parámetros de solicitud

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `file` | file | Sí | Archivo de audio a transcribir, máximo 25 MB. Soporta `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, `webm`. |
| `model` | string | No | `whisper-1` (por defecto) o `gpt-transcribe`, las diferencias de capacidad se ven en la tabla a continuación. |
| `language` | string | No | Idioma del audio, código ISO-639-1 (por ejemplo, `zh`, `en`). Completar puede mejorar la precisión y velocidad; dejar en blanco lo identificará automáticamente. |
| `prompt` | string | No | Palabras clave para guiar el estilo de escritura, o proporcionar nombres propios, términos para mejorar la precisión del reconocimiento. |
| `response_format` | string | No | `whisper-1`: `json` (por defecto), `text`, `srt`, `verbose_json`, `vtt`; `gpt-transcribe`: solo `json`, `text`. |
| `temperature` | number | No | Temperatura de muestreo 0–1, por defecto 0. |
| `timestamp_granularities[]` | array | No | Granularidad de la marca de tiempo, `word` o `segment`, debe usarse con `response_format=verbose_json`. |
| `languages[]` | array | No | Idiomas candidatos (ISO-639-1), **solo `gpt-transcribe`**. Excluyente con `language`, no enviar ambos. |
| `keywords[]` | array | No | Sugerencias de nombres propios/términos, **solo `gpt-transcribe`**, puede mejorar significativamente la precisión del reconocimiento de nombres de marcas y personas. |
| `stream` | boolean | No | Cuando `gpt-transcribe` se establece en `true`, devuelve eventos incrementales SSE; `whisper-1` ignorará este parámetro y devolverá el resultado completo (comportamiento consistente con el oficial de OpenAI). |

## Qué modelo elegir

| | `whisper-1` | `gpt-transcribe` |
| - | - | - |
| Precio | \$0.0078 / minuto | **\$0.0059 / minuto** (más barato) |
| Precisión de reconocimiento | Buena | **Mejor**, especialmente para nombres de marcas y nombres propios |
| Salida de subtítulos (`srt`/`vtt`) | ✅ | ❌ |
| Marca de tiempo a nivel de palabra | ✅ | ❌ |
| `languages[]` / `keywords[]` | ❌ | ✅ |
| Devuelve el idioma detectado | Necesita `verbose_json` | Devuelve por defecto |
| Devolución incremental SSE | ❌ (se ignora `stream`) | ✅ |

**Necesitas subtítulos o marcas de tiempo a nivel de palabra → `whisper-1`; en otros casos, se recomienda `gpt-transcribe`** (más preciso y más barato).

## Ejemplo

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1
```

Respuesta:

```json theme={null}
{
  "text": "La plataforma Ace Data Cloud está probando el punto de reconocimiento de voz. El rápido zorro marrón salta sobre el perro perezoso."
}
```

El audio en chino también es compatible, no es necesario especificar el idioma:

```json theme={null}
{
  "text": "Bienvenido a la plataforma AceData Cloud, estamos probando la interfaz de reconocimiento de voz, hoy es 31 de julio."
}
```

### Generar subtítulos

Establece `response_format` en `srt` o `vtt` para obtener directamente un archivo de subtítulos utilizable:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=srt \
  -o subtitle.srt
```

Contenido de respuesta (`Content-Type: text/plain`):

```
1
00:00:00,000 --> 00:00:03,800
La plataforma Ace Data Cloud está probando el punto de reconocimiento de voz.

2
00:00:03,800 --> 00:00:06,280
El rápido zorro marrón salta sobre el perro perezoso.
```

### Marca de tiempo a nivel de palabra

Si necesitas el tiempo de inicio y fin de cada palabra, usa `verbose_json` junto con `timestamp_granularities[]=word`:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F response_format=verbose_json \
  -F 'timestamp_granularities[]=word'
```

Respuesta:

```json theme={null}
{
  "task": "transcribe",
  "language": "english",
  "duration": 6.29,
  "text": "La plataforma Ace Data Cloud está probando el punto de reconocimiento de voz. El rápido zorro marrón salta sobre el perro perezoso.",
  "words": [
    {
      "word": "La",
      "start": 0.0,
      "end": 0.32
    },
    {
      "word": "plataforma",
      "start": 0.32,
      "end": 0.54
    },
    {
      "word": "Ace",
      "start": 0.54,
      "end": 0.86
    }
  ]
}
```

### Transcripción en streaming

`gpt-transcribe` puede devolver `Content-Type: text/event-stream` a través de `stream=true`. El servicio enviará eventos compatibles con OpenAI:
`transcript.text.delta` lleva texto incremental, `transcript.text.done` lleva texto completo y `usage` y señala la finalización normal.

```shell theme={null}
curl -N -X POST 'https://api.acedata.cloud/v1/audio/transcriptions' \
  -H 'authorization: Bearer {token}' \
  -F file=@audio.mp3 \
  -F model=gpt-transcribe \
  -F stream=true
```

Ejemplo de flujo de eventos:

```text theme={null}
data: {"type":"transcript.text.delta","delta":"Hola"}

data: {"type":"transcript.text.done","text":"Hola mundo","usage":{"type":"tokens","input_tokens":14,"output_tokens":3,"total_tokens":17}}
```

Recibir `transcript.text.done` indica que se ha completado correctamente. Si el procesamiento falla después de establecer el flujo, la conexión finalizará después del evento `event: error`; si el cliente se desconecta, se cancelará este procesamiento y no continuará generando en segundo plano. `whisper-1`, incluso si se pasa `stream=true`, seguirá devolviendo una respuesta normal no en streaming.

### Usar el SDK oficial

```python theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://api.acedata.cloud/v1", api_key="{token}")
with open("audio.mp3", "rb") as f:
    result = client.audio.transcriptions.create(model="whisper-1", file=f)
print(result.text)
```

## Precio

| Modelo | Precio en esta plataforma |
| - | - |
| `whisper-1` | \$0.0078 / minuto |
| `gpt-transcribe` | \$0.0059 / minuto |

> Se cobra según la duración real del audio, menos de 1 segundo se cuenta como 1 segundo, el máximo por una sola vez es de 1 hora.

## Consideraciones

* El tamaño máximo de un solo archivo es **25 MB**. Si excede, divídalo o comprímalo (normalmente reducir la tasa de bits es suficiente, el reconocimiento de voz no requiere alta calidad de audio).
* `gpt-transcribe` soporta `stream=true` SSE; `whisper-1` ignorará `stream` y devolverá el resultado completo.
* Los parámetros son consistentes con la API oficial de OpenAI `/v1/audio/transcriptions`, el SDK oficial solo necesita cambiar `base_url` para funcionar.
* `include[]`, `chunking_strategy`, `known_speaker_names[]`, `known_speaker_references[]` pertenecen a modelos de transcripción que no hemos lanzado, pasarlos devolverá 400 en lugar de ser ignorados silenciosamente. Los parámetros exclusivos del modelo (`timestamp_granularities[]` para `whisper-1`, `languages[]`/`keywords[]` para `gpt-transcribe`) también devolverán 400 si se pasan a un modelo no soportado.
* Las solicitudes pueden tardar, se recomienda que la configuración de tiempo de espera del cliente no sea inferior a 300 segundos.

## Códigos de error

| Código de estado | código | Descripción |
| - | - | - |
| 400 | `bad_request` | No se proporcionó `file`, el archivo no se puede analizar, o los parámetros son inválidos (`model`/`response_format` valores no soportados, `temperature` fuera de 0–1, `timestamp_granularities[]` no acompañado de `verbose_json`, se pasaron parámetros no soportados por `whisper-1`). |
| 401 | `authentication_failed` | Token inválido. |
| 403 | `used_up` | Saldo insuficiente. |
| 413 | `request_too_large` | El archivo de audio excede el límite de 25 MB. |
| 429 | `too_many_requests` | Solicitudes demasiado frecuentes, por favor intente de nuevo más tarde. |
| 500 | `api_error` | Error interno del servicio, por favor intente de nuevo más tarde. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.