# M4A转MP3 API Documentation

> 将公网可访问的 M4A（AAC）音频转为 MP3。本机 ffmpeg 重新编码后立即返回可下载的 MP3 地址，支持指定码率，单文件不超过 80MB。

## Overview

This document describes how to call the **M4A转MP3** API.

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

## 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/m4a2mp3`
- **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 | m4a 公网地址 |
| `bitrate` | No | 码率，可选 64/96/128/192/256/320，默认 128 |
| `output_name` | No | 输出文件名，可选 |

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

### Request Example

```
/api/audio/m4a2mp3?key=你的密钥&url=https://example.com/audio.m4a&bitrate=128
```

## Details

## 请求HEADER：

| 名称 | 值 |
| --- | --- |
| Content-Type | application/x-www-form-urlencoded;charset:utf-8; |
| Content-Type | application/json（JSON 提交时） |

## 请求参数说明：

| 名称 | 必填 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- | --- |
| key | 是 | string | 35kj5jnlj53453kl5j43nj5 | 接口密钥,在控制台->密钥管理查看 |
| url | 是 | string | https://example.com/audio.m4a | 待转换的 m4a 公网地址，必须是 http/https。兼容 audio_url、m4a_url |
| audio_url | 否 | string | https://example.com/audio.m4a | url 的别名，url 为空时生效 |
| m4a_url | 否 | string | https://example.com/audio.m4a | url 的别名，url、audio_url 都为空时生效 |
| bitrate | 否 | int | 128 | 输出 MP3 码率，单位 kbps。仅支持 64 / 96 / 128 / 192 / 256 / 320，默认 128 |
| output_name | 否 | string | voice_001 | 输出文件名（不含扩展名），仅允许字母数字下划线和中划线；不传则自动生成 |

## 返回参数说明：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 状态码，200 表示转换成功 |
| msg | string | 状态信息 |
| data | object | 转换结果 |
| data.url | string | 转换后的 MP3 公网地址 |
| data.audio_url | string | 与 data.url 相同，方便按音频字段取值 |
| data.bytes | int | MP3 文件大小，单位字节 |
| data.bitrate | int | 实际使用的码率，单位 kbps |
| data.duration | float | 音频时长，单位秒；探测失败时为 0 |
| data.job_id | string | 本次转换任务编号 |
| debug | string/array | 调试数据 |
| exec_time | float | 执行耗时 |
| ip | string | 客户端IP |

## 使用说明：

| 项目 | 说明 |
| --- | --- |
| 请求方式 | 同时支持 GET、POST、JSON |
| 转换原理 | 本机 ffmpeg 将 AAC/M4A 解码后用 libmp3lame 重新编码为 MP3，不是改后缀 |
| 文件限制 | 仅接受公网可访问地址，单文件不超过 80MB |
| 计费 | 转换成功后按后台 consume 扣点，失败不扣 |

## Response Example

```json
{
    "code": 200,
    "msg": "转换成功",
    "data": {
        "url": "https://apis.xiaobao.ink/upload/audio_convert/2026/08/31/m4a_20260831100000_abcd1234.mp3",
        "audio_url": "https://apis.xiaobao.ink/upload/audio_convert/2026/08/31/m4a_20260831100000_abcd1234.mp3",
        "bytes": 123456,
        "bitrate": 128,
        "duration": 12.5,
        "job_id": "m4a_20260831100000_abcd1234"
    },
    "exec_time": 1.234567,
    "ip": "1.2.3.4"
}
```

## Error Codes

| 错误码 | 类型 | 说明 |
| --- | --- | --- |
| 200 | int | 转换成功 |
| 400 | int | 参数错误：缺少 url、地址不是 http/https、bitrate 不在允许范围、接口未添加或未开启 |
| 403 | int | 密钥无效或没有权限 |
| 405 | int | 请求方法不支持，仅允许 GET 或 POST |
| 500 | int | 服务器内部错误：音频下载失败、超过 80MB、ffmpeg 不可用或转码失败 |

## 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}`)._