# Doubao-录音文件识别（ASR 极速版）

对已上传的音频文件做语音转文字，返回整段文本与**句级时间戳**。适用于 **混剪、字幕生成、口播拆条** 等「先有音频 URL、再批量识别」的场景。

与 [流式 ASR（WebSocket）](/api-asr-stream-doubao) 的区别：

| 能力 | 极速版（本文） | 流式 ASR |
|------|----------------|----------|
| 协议 | HTTP POST | WebSocket |
| 输入 | 公网可访问的 `audio.url` | 实时 PCM 分片或文件流 |
| 典型场景 | 混剪、离线转写、字幕 | 麦克风实时听写 |
| 平台模型 | `Doubao-ASR-Flash` | `Doubao-ASR-Stream` |

<div class="doc-interface">
  <p><strong>URL</strong>：<code>$BASE_URL/v3/auc/bigmodel/recognize/flash</code></p>
  <p><strong>Method</strong>：<code>POST</code></p>
  <p><strong>Content-Type</strong>：<code>application/json</code></p>
  <p><strong>平台模型</strong>：<code>Doubao-ASR-Flash</code>（固定；请求体中的 <code>model_name</code> 为火山上游参数，填 <code>bigmodel</code> 即可）</p>
</div>

<div class="doc-api-spec">

## 鉴权

公共变量见 [API 接入 · 公共参数](/api-common)。

| 方式 | 说明 |
|------|------|
| `Authorization: Bearer $API_KEY` | **推荐**（服务端 / curl / SDK） |
| `X-Api-App-Key: $API_KEY` | 与火山头同名，值填 **平台 API Key** |
| `x-goog-api-key: $API_KEY` | 兼容 Google 风格客户端 |

API Key 需 **scope 为 `chat` 或 `all`**，且租户 **可用余额 &gt; 0**。

## 请求体

Body 原样转发火山 openspeech，结构如下。

### 顶层字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `user` | object | 否 | 业务用户标识 |
| `user.uid` | string | 否 | 建议填业务侧 uid，便于排查（如 `bosshome-voice`） |
| `audio` | object | **是** | 音频输入 |
| `audio.url` | string | **是** | **公网可访问**的音频地址（wav / mp3 等） |
| `audio.format` | string | 否 | 如 `wav`、`mp3` |
| `audio.rate` | int | 否 | 采样率，如 `16000` |
| `audio.language` | string | 否 | 如 `zh-CN` |
| `request` | object | 否 | 识别参数 |
| `request.model_name` | string | 否 | 火山参数，通常填 `bigmodel` |
| `request.enable_itn` | bool | 否 | 逆文本归一化（数字、日期等） |
| `request.enable_punc` | bool | 否 | 启用标点 |
| `request.show_utterances` | bool | 否 | **混剪建议 true**：返回句级 `start_time` / `end_time` |

### 混剪推荐参数

混剪 / 字幕场景建议至少开启：

- `enable_punc: true` — 带标点，便于展示字幕
- `show_utterances: true` — 返回分句与时间戳（毫秒），用于卡点、字幕轴

### 请求示例

```json
{
  "user": {
    "uid": "bosshome-voice"
  },
  "audio": {
    "url": "https://static.example.com/upload/2026/06/demo.wav",
    "format": "wav",
    "rate": 16000
  },
  "request": {
    "model_name": "bigmodel",
    "enable_itn": true,
    "enable_punc": true,
    "show_utterances": true
  }
}
```

## 响应

成功时 HTTP 200，JSON 示例：

```json
{
  "audio_info": {
    "duration": 12345
  },
  "result": {
    "text": "大家好，欢迎收看本期视频。",
    "utterances": [
      {
        "text": "大家好，",
        "start_time": 0,
        "end_time": 1200,
        "definite": true,
        "words": [
          {
            "text": "大家",
            "start_time": 0,
            "end_time": 600
          }
        ]
      }
    ]
  }
}
```

| 字段 | 说明 |
|------|------|
| `audio_info.duration` | 音频时长（毫秒），用于计费 |
| `result.text` | 整段识别文本 |
| `result.utterances[]` | 句级分句（需 `show_utterances: true`） |
| `utterances[].start_time` / `end_time` | 句起止时间（毫秒） |
| `utterances[].words[]` | 词级时间戳（若上游返回） |

部分响应头可能透传：`X-Api-Status-Code`、`X-Api-Message`、`X-Tt-Logid`。

## CURL 示例

先设置 [公共变量](/api-common)：

```bash
BASE_URL="https://ai.open.thinkzoneai.com"
API_KEY="替换为你的API Key"
```

### 混剪 / 字幕（与 aisee 生产调用一致）

```bash
curl -s -X POST "$BASE_URL/v3/auc/bigmodel/recognize/flash" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": { "uid": "bosshome-voice" },
    "audio": {
      "url": "https://static.example.com/upload/demo.wav",
      "format": "wav",
      "rate": 16000
    },
    "request": {
      "model_name": "bigmodel",
      "enable_itn": true,
      "enable_punc": true,
      "show_utterances": true
    }
  }'
```

### 最简识别（仅 URL）

```bash
curl -s -X POST "$BASE_URL/v3/auc/bigmodel/recognize/flash" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": { "uid": "test-user" },
    "audio": { "url": "https://static.example.com/audio.mp3" },
    "request": {
      "model_name": "bigmodel",
      "show_utterances": true
    }
  }'
```

## Go SDK

```go
import (
    "code.keplerjai.com/keplerjai/campus-amags/pkg"
    "code.keplerjai.com/keplerjai/campus-amags/sdk/amagssdk"
)

// Init 略：amagssdk.Init(host); amagssdk.SetAPIKey(key)

// 方式一：快捷（默认 ITN + utterances，不含 enable_punc）
result, err := amagssdk.RecognizeAsrFlashByURL(audioURL, "bosshome-voice")

// 方式二：混剪完整参数（推荐）
enableITN, enablePunc, showUtterances := true, true, true
result, err = amagssdk.RecognizeAsrFlash(pkg.VolcengineAsrFlashReq{
    User: &pkg.VolcengineAsrFlashUser{UID: "bosshome-voice"},
    Audio: pkg.VolcengineAsrFlashAudio{
        URL:    audioURL,
        Format: "wav",
        Rate:   16000,
    },
    Request: &pkg.VolcengineAsrFlashRequest{
        ModelName:      "bigmodel",
        EnableITN:      &enableITN,
        EnablePunc:     &enablePunc,
        ShowUtterances: &showUtterances,
    },
})

text := amagssdk.AsrFlashText(result)
for _, u := range amagssdk.AsrFlashUtterances(result) {
    // u.StartTime, u.EndTime, u.Text — 用于字幕轴 / 混剪卡点
}
```

## 计费

- **模型**：`Doubao-ASR-Flash`（`type=audio`）
- **维度**：`asr_duration_ms`（识别音频时长，毫秒）
- **任务**：每次调用创建 `audio` 类型任务，成功后按时长结算

## 常见错误

| HTTP | 原因 | 处理 |
|------|------|------|
| 401 | API Key 无效 / 未传 | 检查 `Authorization: Bearer` |
| 400 | 模型未启用、`doubao-speech` 配置 JSON 非法、余额为 0、scope 不足 | 查响应 `resultMsg` 或任务表 `error_message` |
| 4xx/5xx（上游 body） | 音频 URL 不可达、格式不支持 | 确保 URL 公网可访问，格式为 wav/mp3 等 |

**注意**：`audio.url` 必须能被 **服务端**（平台 → 火山）拉取，内网地址或需鉴权的私有链通常会失败。

## 接入说明（aisee 混剪）

aisee 混剪管线典型流程：

1. 导出或上传混剪音频到 OSS/CDN，得到公网 URL  
2. **POST** `$BASE_URL/v3/auc/bigmodel/recognize/flash`（**不要**用 WebSocket 流式接口）  
3. 解析 `result.utterances` 生成字幕轨或按句切分素材  

业务侧 `user.uid` 可使用固定标识（如 `bosshome-voice`）便于日志关联。

## 参考

- [火山引擎 · 大模型录音文件识别 API（极速版）](https://www.volcengine.com/docs/6561/80818?lang=zh)
- [流式 ASR（WebSocket）](/api-asr-stream-doubao) — 实时麦克风场景
- [文字转语音 T2A](/api-t2a-minimax) — 混剪口播配音

</div>