# 语音转文本字幕版 API Documentation

> 语音识别角色字幕文案：音视频转写并返回 SRT 字幕、说话人与词级时间戳。提交 url 返回 taskId，再查询结果。按分钟计费，0.05 元/分钟。

## Overview

This document describes how to call the **语音转文本字幕版** API.

- **Model / path slug**: `audio/audiototext`
- **Task type**: `sync` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/42`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `GET|POST https://apis.xiaobao.ink/api/audio/audiototext`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `GET / POST`
- **Note**: This endpoint accepts both GET query parameters and POST form/JSON body.

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `url` | Yes | 音频或视频公网URL，提交任务时必填 |
| `taskId` | Yes | 查询任务ID，查询时必填，提交时不用传 |
| `language` | No | 可选，zh/en/ja/yue/ko/de/fr/ru，留空自动识别 |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
/api/audio/audiototext?key=你的key&url=https://example.com/demo.mp3
```

## Details

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/x-www-form-urlencoded;charset:utf-8; 或 application/json |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| key | 是 | string | 35kj5jnlj53453kl5j43nj5 | 接口密钥,在控制台->密钥管理查看 |
| url | 否 | string | https://example.com/demo.mp3 | 视频或音频公网 URL，提交任务时必填（兼容 audio_url）。支持 mp3、mp4、wav、m4a、aac、flac、ogg 等，最大 2GB / 12 小时 |
| taskId | 否 | string | 640c4f3f-6545-4102-88f6-703a826bdd14 | 查询任务 ID，查询时必填（兼容 task_id）；提交任务时不用传 |
| language | 否 | string | zh | 识别语言，留空自动识别。支持：zh 中文、en 英文、ja 日语、yue 粤语、ko 韩语、de 德语、fr 法语、ru 俄语 |

提交传 url，查询传 taskId。计费按音频时长，不足 1 分钟按 1 分钟；单价 5 点/分钟（约 0.05 元/分钟）。查询不扣费。提交成功即扣费；若未能探测时长，先按 1 分钟预扣，查询成功后若实际更长再补扣差额。

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 状态码，200 表示成功 |
| msg | string | 状态信息 |
| data | object | 请求结果数据集 |
| data.taskId | string | 任务ID |
| data.url | string | 音频/视频地址 |
| data.format | string | 格式 |
| data.seconds | string | 时长（秒） |
| data.sampling_rate | string | 采样率 |
| data.task_status | string | PENDING 已提交、RUNNING 处理中、SUCCEEDED 成功、FAILED 失败、UNKNOWN 过期或不存在 |
| data.submission_time | string | 提交时间 |
| data.completion_time | string | 完成时间 |
| data.text | string | 识别文本 |
| data.subtitle | string | 组装好的 SRT 字幕，可直接保存为 .srt |
| data.srt | string | 同 subtitle，便于直接使用 |
| data.sentences | array | 含 speaker 说话人、句级时间戳、words 词级时间戳 |
| data.bill_minutes | int | 计费分钟数（提交时返回） |
| data.power_cost | number | 本次扣除点数（提交时返回） |
| debug | string/array | 调试数据 |
| exec_time | float | 执行耗时 |
| ip | string | 客户端IP |

## Response Example

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "taskId": "640c4f3f-6545-4102-88f6-703a826bdd14",
        "task_id": "640c4f3f-6545-4102-88f6-703a826bdd14",
        "url": "https://example.com/demo.mp3",
        "format": "mp3",
        "seconds": "12.8",
        "sampling_rate": "16000",
        "task_status": "SUCCEEDED",
        "text": "大家好，欢迎使用语音转文本字幕接口。",
        "subtitle": "1\n00:00:00,500 --> 00:00:04,200\n大家好，欢迎使用语音转文本字幕接口。\n",
        "srt": "1\n00:00:00,500 --> 00:00:04,200\n大家好，欢迎使用语音转文本字幕接口。\n",
        "sentences": [
            {
                "speaker": "1",
                "sentence": "大家好，欢迎使用语音转文本字幕接口。",
                "start_time": 500,
                "end_time": 4200,
                "words": [
                    {
                        "word": "大",
                        "start_time": 500,
                        "end_time": 700
                    },
                    {
                        "word": "家",
                        "start_time": 700,
                        "end_time": 900
                    }
                ]
            }
        ]
    },
    "exec_time": 0.32,
    "ip": "1.2.3.4"
}
```

## Error Codes

| 错误码 | 类型 | 说明 |
| --- | --- | --- |
| 403 | int | 没有权限 / 密钥无效 |
| 400 | int | 参数传递不正确或点数不足 |
| 500 | int | 服务器内部错误 |

## Usage Flow

1. Obtain your API Key from the console
2. Call the endpoint with `key` and required parameters
3. Parse the JSON (or binary) response according to the examples above

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._