开放 API · 设备曲线与歌词

版本：1.3
更新：2026-10-28
服务地址：https://api.androeq.cc
文档地址：https://api.androeq.cc（https://www.androeq.cc 同样可用，两个域名走同一套接口）

本文档面向使用 API Key 的外部客户端，覆盖设备曲线、歌词识别和独立歌词翻译接口。

1. 快速开始#

bash

curl -sS "https://api.androeq.cc/api/v1/curves?page_size=5" \
  -H "X-API-Key: eqk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

所有 /api/v1/* 接口统一使用请求头：

http

X-API-Key: eqk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key 在「我的后台 · API」申请。密钥只显示一次，请自行保存；密钥带 scopes 权限：

scope	可访问接口
`curves`	`/api/v1/curves*`
`lyrics`	`/api/v1/lyrics/*`
`curves,lyrics`	两组都可用

权限不足返回 403 scope_denied，密钥无效或停用返回 401 bad_api_key。

2. 通用约定#

2.1 请求与响应#

普通接口使用 Content-Type: application/json；
歌词识别上传接口使用 原始 WAV 二进制，不是 multipart；
响应统一为 UTF-8 JSON；
时间戳单位为秒，浮点数；
文本字段不会返回 null，缺失时返回空串或省略可选字段。

2.2 错误格式#

json

{
  "error": "人类可读的错误说明",
  "code": "machine_readable_code"
}

HTTP	code	含义
400	`bad_request` / `bad_target` / `empty_text`	参数缺失或不合法
401	`bad_api_key`	没有 Key、Key 无效、被停用或账号被封禁
402	`quota_exceeded`	本月音频秒数额度用完
403	`scope_denied`	Key 没有对应接口权限
404	`not_found` / `no_job`	资源或任务不存在
413	`too_large` / `too_long`	上传音频或文本超限
429	`quota_exceeded` / 限流	调用次数用完或被 IP 限流；限流响应带 `Retry-After`
500	—	服务内部错误
502	`translate_failed`	上游翻译服务失败
503	`translate_unavailable`	本地翻译模型不可用

2.3 计费与额度#

额度单位是 音频秒数，记录在 API Key 的 used_seconds / quota_seconds；
每月 1 号 00:00 UTC 自动清零；
quota_seconds <= 0 表示不限量；
失败请求会尽量退回已扣秒数；
实际扣费以响应里的 billed_seconds 为准。

3. 设备曲线#

3.1 曲线列表#

http

GET /api/v1/curves

免费，只校验 Key，不扣额度。

参数	类型	默认	说明
`q`	string	—	按名称模糊搜索
`type`	int	—	`0` 头戴、`1` 入耳、`2` 其他（以服务端 `typeName` 为准）
`source`	string	—	`official` 或 `user`
`primary`	0/1	`1`	`1` 只返回主型号，`0` 包含变体
`page`	int	`1`	页码
`page_size`	int	`100`	每页 1–500

响应：

json

{
  "version": 1760000000,
  "total": 6802,
  "page": 1,
  "pageSize": 100,
  "items": [
    {
      "id": 123,
      "name": "Example Headphone",
      "type": 0,
      "typeName": "头戴",
      "rig": "rig_xxx",
      "source": "official",
      "author": "官方",
      "points": 696,
      "primary": true,
      "variants": 0,
      "updatedAt": 1760000000
    }
  ]
}

version 是当前筛选条件下的最大更新时间。客户端可缓存列表，先比较 version，相同则整段跳过。

3.2 曲线详情#

http

GET /api/v1/curves/{id}

参数	类型	默认	说明
`points`	int	全精度	目标点数，最小 8；服务端按等间隔降采样

响应：

json

{
  "id": 123,
  "name": "Example Headphone",
  "type": 0,
  "typeName": "头戴",
  "rig": "rig_xxx",
  "source": "official",
  "author": "官方",
  "description": "",
  "count": 696,
  "unit": ["Hz", "dB"],
  "points": [
    [20.0, 3.6],
    [21.2, 3.5],
    [1000.0, 0.0]
  ]
}

只返回 visibility = public 的曲线；不存在和不公开都返回 404 not_found，不提供 ID 探测。

4. 歌词识别#

4.1 提交流程#

text

POST /api/v1/lyrics/recognize  →  job
GET  /api/v1/lyrics/result?job=…  →  status / text / text_zh / lines

识别在服务端串行队列执行，客户端轮询结果即可。

4.2 提交识别#

http

POST /api/v1/lyrics/recognize
Content-Type: audio/wav
X-API-Key: eqk_...

音频格式固定：

16 kHz
单声道
s16le PCM
44 字节 WAV 头
最大 40 MB（约 21 分钟）

查询参数：

参数	默认	说明
`translate=1`	`0`	额外翻译成中文
`precise=1`	`0`	精确歌词（逐词时间轴，隐含翻译）

计费倍率（在识别完成后最终确认）：

参数	倍率
无	×1
`translate=1`	×2
`precise=1`	×4

响应：

json

{
  "job": "9ad5e63943e981a3a134ad5df090dd77565396e7",
  "status": "queued",
  "queue": 2
}

缓存命中时直接返回：

json

{
  "job": "9ad5e63943e981a3a134ad5df090dd77565396e7",
  "status": "done",
  "cached": true,
  "text": "[00:01.00] Hello world",
  "multiplier": 1,
  "billed_seconds": 10
}

4.3 查询结果#

http

GET /api/v1/lyrics/result?job={job}

免费，可以频繁轮询；建议 1–2 秒一次。

可选参数：

参数	说明
`level=word`	额外返回 `segs` 逐词/逐字时间轴（仅 precise 任务）

完成响应：

json

{
  "job": "9ad5...",
  "status": "done",
  "text": "[00:01.00] Hello world\n[00:03.50] This is a test.",
  "has_zh": true,
  "text_zh": "[00:01.00] 你好世界\n[00:03.50] 这是一个测试。",
  "lines": [
    {
      "start": 1.0,
      "end": 3.2,
      "text": "Hello world",
      "zh": "你好世界"
    }
  ]
}

状态：

status	含义
`queued`	已入队
`running`	识别/翻译中，`stage` 表示当前阶段
`done`	完成
`error`	失败，`error` 为原因

lines 中纯器乐段可能使用 [MUSIC]，zh 可能为空串。

5. 独立歌词翻译#

已经拿到歌词文本，或已经识别过一首歌，只需要翻译时使用本接口。它不重新跑识别：

本地模型：按音频秒数 × 0.5 计费；
百度翻译：调用方自己的百度账号结算，不扣本站时长。

http

POST /api/v1/lyrics/translate
Content-Type: application/json
X-API-Key: eqk_...

5.1 请求#

两种输入方式二选一：

A. 直接传文本

json

{
  "text": "[00:01.00] 君のことが好きです\n[00:03.50] ずっと一緒にいたい",
  "target": "zh",
  "duration": 12
}

B. 翻译已有识别任务

json

{
  "job": "9ad5e63943e981a3a134ad5df090dd77565396e7",
  "target": "zh"
}

字段：

字段	类型	必需	说明
`text`	string	二选一	LRC 或纯文本，最多 12000 字符；时间戳原样保留
`job`	string	二选一	已有歌词任务号，服务端读取原文与音频秒数
`duration`	number	否	原音频秒数；不传时按 20 字符/秒折算
`target`	string	否	`zh`（默认）/ `en` / `ja` / `ko`
`source`	string	否	`auto`（默认）/ `zh` / `en` / `ja` / `ko`

5.2 计费#

text

base_seconds = duration
             或 job 对应的 flags.seconds
             或 max(1, 字符数 / 20)

本地模型：billed_seconds = max(1, ceil(base_seconds × 0.5))
百度翻译：billed_seconds = 0

示例：duration = 12，本地模型扣 6 秒，multiplier = 0.5；使用百度凭据则扣 0 秒，multiplier = 0，billing = "baidu_free"。

本地扣费发生在翻译前；翻译失败会自动退回；
百度翻译不扣本站时长，失败也不会产生扣费；
job 模式不会重复收识别费；
本地模式额度不足返回 402 quota_exceeded；百度模式不受本站额度限制。

5.3 响应#

json

{
  "ok": true,
  "status": "done",
  "text": "[00:01.00] 我喜欢你\n[00:03.50] 我想和你在一起",
  "translated": "[00:01.00] 我喜欢你\n[00:03.50] 我想和你在一起",
  "source": "auto",
  "target": "zh",
  "chars": 41,
  "base_seconds": 12,
  "billed_seconds": 6,
  "multiplier": 0.5,
  "billing": "local_half"
}

字段说明：

字段	说明
`text` / `translated`	相同内容，二选一读取即可
`source`	请求的源语言或 `auto`
`target`	目标语言
`chars`	原文有效字符数
`base_seconds`	计费基准秒数
`billed_seconds`	本次实际扣费
`multiplier`	本地 `0.5`；百度 `0`
`billing`	`local_half` 或 `baidu_free`

5.4 翻译来源#

默认使用服务器本地离线模型：

日 / 英 / 韩 / 俄 → 中文；
日 / 韩 / 俄 → 英文；
英 → 中文。
本地模式的目标语言实际为 zh / en；target=ja / ko 需要提供百度凭据。

如果请求头同时提供百度翻译凭据，则优先使用百度：

http

X-Baidu-AppId: your-app-id
X-Baidu-Key: your-key

百度凭据只用于本次请求，不会持久化到服务器。

5.5 示例#

bash

curl -sS -X POST "https://api.androeq.cc/api/v1/lyrics/translate" \
  -H "X-API-Key: eqk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "[00:01.00] 君のことが好きです\n[00:03.50] ずっと一緒にいたい",
    "target": "zh",
    "duration": 12
  }'

Python：

python

import requests

resp = requests.post(
    "https://api.androeq.cc/api/v1/lyrics/translate",
    headers={"X-API-Key": "eqk_xxx"},
    json={
        "text": "[00:01.00] Hello world",
        "target": "zh",
        "duration": 10,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["text"])
print("billed:", data["billed_seconds"], "seconds")

6. 计费汇总#

接口	计费
`GET /api/v1/curves`	免费
`GET /api/v1/curves/{id}`	免费
`POST /api/v1/lyrics/recognize`	音频秒数 × 1 / 2 / 4
`GET /api/v1/lyrics/result`	免费
`POST /api/v1/lyrics/translate`	本地 ×0.5；百度免费

7. 版本记录#

版本	日期	变更
1.3	2026-10-28	文档站迁到 `api.androeq.cc`（深色文档站，含插件文档）；接口在 `api.androeq.cc` 与 `www.androeq.cc` 双域名可用
1.2	2026-10-25	百度翻译不扣本站时长；本地模型仍按 0.5× 计费；新增 `billing` 字段
1.1	2026-10-25	新增独立歌词翻译接口，0.5× 计费；翻译失败自动退款；支持本地离线模型和可选百度凭据
1.0	2026-10	设备曲线、歌词识别、结果查询、API Key 额度体系

8. 支持#

文档：https://api.androeq.cc
后台：https://www.androeq.cc/app#/mine/api
技术支持 QQ：2320905315

ANDROEQ+ 开放 API 文档

1. 快速开始#

2. 通用约定#

2.1 请求与响应#

2.2 错误格式#

2.3 计费与额度#

3. 设备曲线#

3.1 曲线列表#

3.2 曲线详情#

4. 歌词识别#

4.1 提交流程#

4.2 提交识别#

4.3 查询结果#

5. 独立歌词翻译#

5.1 请求#

5.2 计费#

5.3 响应#

5.4 翻译来源#

5.5 示例#

6. 计费汇总#

7. 版本记录#

8. 支持#