# see2ai_voice_recognition_v1

> 豆包流式语音识别服务，支持把用户录音实时转写为文本

## 📖 接入指引

**Endpoint**: `POST /api/v1/actions/see2ai_voice_recognition_v1`

**认证方式**: Bearer Token (租户 API Key)

> **⚠️ 重要提示**
> 
> 本 API 是 SEE2AI 平台封装后的接口，**参数格式与上游官方（如火山引擎、OpenAI等）API 不同**。
> 请直接使用下方 Schema 中定义的参数，无需参考官方文档。
> 
> *例如：*
> *- 文本模型参数可能是 `query` 而不是 `messages` 数组*
> *- 视频模型参数可能是 `brief` (创意简报) 而不是复杂的配置项*

## 📥 输入参数 (Input Schema)

```json
{
  "properties": {
    "audio_base64": {
      "description": "待识别音频的 base64 内容，支持 pcm 或 wav",
      "title": "Audio Base64",
      "type": "string"
    },
    "audio_format": {
      "default": "wav",
      "description": "音频格式：pcm 或 wav",
      "title": "Audio Format",
      "type": "string"
    },
    "language": {
      "default": "zh-CN",
      "description": "识别语言，默认 zh-CN",
      "title": "Language",
      "type": "string"
    },
    "resource_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "可选覆盖 Resource ID",
      "title": "Resource Id"
    }
  },
  "required": [
    "audio_base64"
  ],
  "title": "VoiceRecognitionInput",
  "type": "object"
}
```

### 参数说明

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `audio_base64` | string | ✅ 是 | `-` | 待识别音频的 base64 内容，支持 pcm 或 wav |
| `audio_format` | string | ❌ 否 | `wav` | 音频格式：pcm 或 wav |
| `language` | string | ❌ 否 | `zh-CN` | 识别语言，默认 zh-CN |
| `resource_id` | string | ❌ 否 | `-` | 可选覆盖 Resource ID |

## 📤 输出结果 (Output Schema)

```json
{
  "properties": {
    "input_tokens": {
      "default": 0,
      "description": "输入消耗的词元数量",
      "title": "Input Tokens",
      "type": "integer"
    },
    "output_tokens": {
      "default": 0,
      "description": "输出消耗的词元数量",
      "title": "Output Tokens",
      "type": "integer"
    },
    "total_tokens": {
      "default": 0,
      "description": "总消耗的词元数量",
      "title": "Total Tokens",
      "type": "integer"
    },
    "model": {
      "default": "",
      "description": "实际使用的模型名称（由各 action 显式填写）",
      "title": "Model",
      "type": "string"
    },
    "source": {
      "default": "",
      "description": "模型提供商（由各 action 显式填写）",
      "title": "Source",
      "type": "string"
    },
    "cost_points": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算）",
      "title": "Cost Points"
    },
    "text": {
      "default": "",
      "description": "识别得到的文本",
      "title": "Text",
      "type": "string"
    },
    "utterances": {
      "description": "分句结果",
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Utterances",
      "type": "array"
    },
    "audio_duration_ms": {
      "default": 0,
      "description": "音频时长（毫秒）",
      "title": "Audio Duration Ms",
      "type": "integer"
    },
    "provider_name": {
      "default": "",
      "description": "底层供应商（实际命中的 provider_configs.name）",
      "title": "Provider Name",
      "type": "string"
    }
  },
  "title": "VoiceRecognitionOutput",
  "type": "object"
}
```

### 输出字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `input_tokens` | integer | 输入消耗的词元数量 |
| `output_tokens` | integer | 输出消耗的词元数量 |
| `total_tokens` | integer | 总消耗的词元数量 |
| `model` | string | 实际使用的模型名称（由各 action 显式填写） |
| `source` | string | 模型提供商（由各 action 显式填写） |
| `cost_points` | string | 预先计算的扣费词元（如果插件内部已经计算好费用，则直接使用此值，忽略基于词元的计算） |
| `text` | string | 识别得到的文本 |
| `utterances` | array | 分句结果 |
| `audio_duration_ms` | integer | 音频时长（毫秒） |
| `provider_name` | string | 底层供应商（实际命中的 provider_configs.name） |

## 💡 调用示例

### cURL 示例

```bash
curl -X POST "https://see2ai.com/api/v1/actions/see2ai_voice_recognition_v1" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-your-tenant-api-key" \
     -d '{
  "audio_base64": "示例值",
  "audio_format": "示例值",
  "language": "示例值",
  "resource_id": "示例值"
}'
```

### Python 示例

```python
import requests

API_KEY = "sk-your-tenant-api-key"
ENDPOINT = "https://see2ai.com/api/v1/actions/see2ai_voice_recognition_v1"

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

payload = {
  "audio_base64": "\u793a\u4f8b\u503c",
  "audio_format": "\u793a\u4f8b\u503c",
  "language": "\u793a\u4f8b\u503c",
  "resource_id": "\u793a\u4f8b\u503c"
}

response = requests.post(ENDPOINT, json=payload, headers=headers)
result = response.json()

print(f"结果：{result}")
```

## 💰 计费说明

> 按音频时长与豆包语音识别资源计费，当前先走平台内部供应商配置

**注意**: 所有费用都以词元为单位，系统会自动从租户余额中扣除。

## ⚠️ 常见错误码

| HTTP 状态码 | 错误原因 | 解决方案 |
| --- | --- | --- |
| `401` | API Key 无效或租户余额不足 | 检查 API Key 是否正确，或联系管理员充值 |
| `422` | 输入参数格式错误（未通过 Schema 校验） | 检查请求参数是否符合 Schema 要求 |
| `500` | 上游模型调用失败或内部处理异常 | 稍后重试，如持续失败请联系技术支持 |

## 📞 技术支持

- **文档问题**: 查看 [SEE2AI 官方文档](https://see2ai.com/docs)
- **API 状态**: 访问 [服务状态页面](https://see2ai.com/status)
- **问题反馈**: 联系技术支持团队

---

**API 版本**: see2ai_voice_recognition_v1
**最后更新**: 2026-03-23