> ## 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 Reconhecimento de Voz da OpenAI (/v1/audio/transcriptions)

> OpenAI generation API guide - Ace Data Cloud

Transcreva áudio para texto, **totalmente compatível com o `/v1/audio/transcriptions` da OpenAI**. Qualquer SDK da OpenAI pode simplesmente apontar `base_url` para `https://api.acedata.cloud` e trocar a chave pelo seu Token AceData para uso direto. Suporta resposta completa padrão e também transcrição incremental SSE do `gpt-transcribe`.

* **URL da solicitação**: `POST https://api.acedata.cloud/v1/audio/transcriptions` (também conhecido como `POST /openai/audio/transcriptions`)
* **Autenticação**: Cabeçalho da solicitação `Authorization: Bearer {token}`
* **Formato da solicitação**: `multipart/form-data`
* **Cobrança**: Cobrança com base na duração do áudio (veja a tabela abaixo), menos de 1 segundo é cobrado como 1 segundo.

## Parâmetros da Solicitação

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `file` | file | Sim | Arquivo de áudio a ser transcrito, máximo de 25 MB. Suporta `flac`, `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `ogg`, `wav`, `webm`. |
| `model` | string | Não | `whisper-1` (padrão) ou `gpt-transcribe`, diferenças de capacidade estão na tabela abaixo. |
| `language` | string | Não | Idioma do áudio, código ISO-639-1 (como `zh`, `en`). Preencher pode aumentar a precisão e a velocidade; deixar em branco resulta em reconhecimento automático. |
| `prompt` | string | Não | Palavra-chave para guiar o estilo de escrita ou fornecer nomes próprios e termos para aumentar a precisão do reconhecimento. |
| `response_format` | string | Não | `whisper-1`: `json` (padrão), `text`, `srt`, `verbose_json`, `vtt`; `gpt-transcribe`: apenas `json`, `text`. |
| `temperature` | number | Não | Temperatura de amostragem 0–1, padrão 0. |
| `timestamp_granularities[]` | array | Não | Granularidade do timestamp, `word` ou `segment`, deve ser usado com `response_format=verbose_json`. |
| `languages[]` | array | Não | Idiomas candidatos (ISO-639-1), **apenas `gpt-transcribe`**. Exclui `language`, não envie ambos. |
| `keywords[]` | array | Não | Sugestões de nomes próprios/termos, **apenas `gpt-transcribe`**, pode aumentar significativamente a precisão do reconhecimento de nomes de marcas e pessoas. |
| `stream` | boolean | Não | Quando `gpt-transcribe` é definido como `true`, retorna eventos incrementais SSE; `whisper-1` ignorará este parâmetro e retornará o resultado completo (comportamento consistente com o oficial da OpenAI). |

## Qual modelo escolher

| | `whisper-1` | `gpt-transcribe` |
| - | - | - |
| Preço | \$0.0078 / minuto | **\$0.0059 / minuto** (mais barato) |
| Taxa de precisão de reconhecimento | Boa | **Melhor**, especialmente para nomes de marcas e termos próprios |
| Saída de legendas (`srt`/`vtt`) | ✅ | ❌ |
| Timestamp em nível de palavra | ✅ | ❌ |
| `languages[]` / `keywords[]` | ❌ | ✅ |
| Retorna idioma detectado | Necessita `verbose_json` | Retorno padrão |
| Retorno incremental SSE | ❌ ( `stream` é ignorado) | ✅ |

**Precisa de legendas ou timestamps em nível de palavra → `whisper-1`; para outros cenários, recomenda-se `gpt-transcribe`** (mais preciso e mais barato).

## Exemplo

```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
```

Retorno:

```json theme={null}
{
  "text": "A plataforma Ace Data Cloud está testando o endpoint de reconhecimento de fala. A rápida raposa marrom salta sobre o cachorro preguiçoso."
}
```

Áudio em chinês também é suportado, sem necessidade de especificar o idioma:

```json theme={null}
{
  "text": "欢迎使用 AceData Cloud 平台,我们正在测试语音识别接口,今天是 7 月 31 号。"
}
```

### Gerar Legendas

Defina `response_format` como `srt` ou `vtt` para obter diretamente um arquivo de legenda utilizável:

```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
```

Conteúdo retornado (`Content-Type: text/plain`):

```
1
00:00:00,000 --> 00:00:03,800
A plataforma Ace Data Cloud está testando o endpoint de reconhecimento de fala.

2
00:00:03,800 --> 00:00:06,280
A rápida raposa marrom salta sobre o cachorro preguiçoso.
```

### Timestamp em Nível de Palavra

Se precisar do tempo de início e fim de cada palavra, use `verbose_json` junto com `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'
```

Retorno:

```json theme={null}
{
  "task": "transcribe",
  "language": "english",
  "duration": 6.29,
  "text": "A plataforma Ace Data Cloud está testando o endpoint de reconhecimento de fala. A rápida raposa marrom salta sobre o cachorro preguiçoso.",
  "words": [
    {
      "word": "Ace",
      "start": 0.0,
      "end": 0.32
    },
    {
      "word": "Data",
      "start": 0.32,
      "end": 0.54
    },
    {
      "word": "Cloud",
      "start": 0.54,
      "end": 0.86
    }
  ]
}
```

### Transcrição em Fluxo

`gpt-transcribe` pode retornar `Content-Type: text/event-stream` com `stream=true`. O serviço enviará eventos compatíveis com a OpenAI:
`transcript.text.delta` carrega texto incremental, `transcript.text.done` carrega texto completo e `usage` e indica conclusão 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
```

Exemplo de fluxo de eventos:

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

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

Receber `transcript.text.done` indica conclusão normal. Se o processamento falhar após a conexão ser estabelecida, a conexão será encerrada após o evento `event: error`; desconectar ativamente do cliente cancelará o processamento atual e não continuará em segundo plano. `whisper-1`, mesmo com `stream=true`, ainda retornará como resposta não em fluxo.

### Usando o 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)
```

## Preços

| Modelo | Preço na plataforma |
| - | - |
| `whisper-1` | \$0.0078 / minuto |
| `gpt-transcribe` | \$0.0059 / minuto |

> Cobrança baseada na duração real do áudio, menos de 1 segundo é cobrado como 1 segundo, o máximo por vez é de 1 hora.

## Observações

* O tamanho máximo de um único arquivo é **25 MB**. Se exceder, divida ou comprima (reduzir a taxa de bits geralmente é suficiente, o reconhecimento de voz não exige alta qualidade de áudio).
* `gpt-transcribe` suporta `stream=true` SSE; `whisper-1` ignorará `stream` e retornará o resultado completo.
* Os parâmetros são consistentes com a API oficial da OpenAI `/v1/audio/transcriptions`, o SDK oficial só precisa alterar o `base_url` para funcionar.
* `include[]`, `chunking_strategy`, `known_speaker_names[]`, `known_speaker_references[]` pertencem a modelos de transcrição que ainda não estão disponíveis, passar esses parâmetros retornará 400 em vez de ser ignorado silenciosamente. Parâmetros exclusivos do modelo (`timestamp_granularities[]` para `whisper-1`, `languages[]`/`keywords[]` para `gpt-transcribe`) também retornarão 400 se passados para um modelo não suportado.
* As solicitações podem demorar, recomenda-se que o tempo limite do cliente não seja inferior a 300 segundos.

## Códigos de erro

| Código de status | código | Descrição |
| - | - | - |
| 400 | `bad_request` | `file` não fornecido, arquivo não pode ser analisado, ou parâmetros inválidos (`model`/`response_format` valores não suportados, `temperature` fora de 0–1, `timestamp_granularities[]` não combinado com `verbose_json`, parâmetros não suportados passados para `whisper-1`). |
| 401 | `authentication_failed` | token inválido. |
| 403 | `used_up` | Saldo insuficiente. |
| 413 | `request_too_large` | O arquivo de áudio excede o limite de 25 MB. |
| 429 | `too_many_requests` | Solicitações muito frequentes, por favor, tente novamente mais tarde. |
| 500 | `api_error` | Erro interno do serviço, por favor, tente novamente mais tarde. |


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