# AI Builder Space 语音识别接口（文件转写）

## 基本信息

- Base URL：`https://space.ai-builders.com/backend/v1`
- 鉴权：每个请求带 HTTP 头 `Authorization: Bearer <你的 API key>`（key 形如 `sk_...`）。key 无效时返回 401，body 为 `{"detail":{"code":"invalid_api_key","message":"Invalid API key."}}`。

## 推荐：Grok 文件转写

`POST https://space.ai-builders.com/backend/v1/audio/grok-transcription`

请求体是 `multipart/form-data`：

| 字段 | 必填 | 说明 |
|---|---|---|
| `audio_file` | 是 | 上传的音频文件。按文件扩展名判断格式，支持 M4A/AAC、WAV、MP3、OGG/Opus、FLAC、MP4、MKV、WebM、raw PCM。 |
| `language` | 否 | BCP-47 语言提示，例如 `zh`。不填则自动识别。 |
| `terms` | 否 | 逗号分隔的词表（人名、术语），最多 100 个，每个不超过 50 字符。 |
| `format` | 否 | 反向文本规范化；只有同时给了 `language` 才生效。 |
| `diarize` | 否 | 说话人标注。 |
| `simple` | 否 | 设为 `true` 时只返回 `{"text": "..."}`。默认返回完整结果。 |

这个接口不支持自由格式的 prompt。

### 返回

`simple=true` 时：

```json
{"text": "嗯，今天下午跟韩宇还有令思远对了一下部署的事情，……"}
```

默认（完整结果）：

```json
{
  "request_id": "b32116c2-...",
  "text": "嗯，今天下午跟韩宇……",
  "detected_language": "zh-cn",
  "duration_seconds": 15.76,
  "words": [{"start": 0.08, "end": 0.1, "text": "嗯", "confidence": null, "speaker": null}],
  "segments": [{"start": 0.08, "end": 15.62, "text": "……", "speaker": null}],
  "billing": {"duration_seconds": 15.76, "duration_hours": 0.0044, "total_cost": 0.00044, "provider": "grok_stt"}
}
```

转写文本在 `text` 字段。

### curl 示例

```bash
curl -s https://space.ai-builders.com/backend/v1/audio/grok-transcription \
  -H "Authorization: Bearer $AI_BUILDER_TOKEN" \
  -F audio_file=@memos/example.wav \
  -F language=zh \
  -F simple=true
```

## 另一个：OpenAI 兼容转写

`POST https://space.ai-builders.com/backend/v1/audio/transcriptions`，与 OpenAI 的 transcriptions 接口兼容（multipart 字段 `file`，以及 `model`）。返回 JSON 的 `text` 字段是转写文本。