接口清单
所有接口基础路径：https://api.soundtitle.org/v1（规划中）。以下 slug 为相对路径。
授权档位说明：传输档 = 免额外授权（通话即授权）；公开 = 永远开放；创作档 = 需单独授权；受限档 = 需申请→批准→限时令牌。
1. 通话再生（传输档）
实时通话中的声音再生——本人正在发声，库代为传输，免额外授权。
| 接口名（slug） | 方法 | 输入 | 输出 | 授权档位 | 收费模式 |
|---|---|---|---|---|---|
transmit-realtime |
POST | profile_id, audio_stream, codebook_version |
audio_stream（再生音频流） |
传输档 | 按通话时长计量 |
transmit-session-status |
GET | session_id |
{ status, duration, bytes_transmitted } |
传输档 | 免费 |
2. 核验查册（公开）
查询一段声音是否经本人授权用于指定用途。永远公开，按次收费。
| 接口名（slug） | 方法 | 输入 | 输出 | 授权档位 | 收费模式 |
|---|---|---|---|---|---|
verify |
POST | profile_id, audio_sample, purpose |
{ status, receipt_id, timestamp } |
公开 | 按次收费 |
verify-batch |
POST | [{ profile_id, audio_hash, purpose }] |
[{ profile_id, status, receipt_id }] |
公开 | 批量折扣 |
3. 生成 API（创作档）
生成本人未说过的话。需单独授权，按字/秒双重计量，强制输出成分表。合成新作必须标明"合成新作，非本人生前演唱/发声"。
| 接口名（slug） | 方法 | 输入 | 输出 | 授权档位 | 收费模式 |
|---|---|---|---|---|---|
generate |
POST | profile_id, text, style_ref, purpose |
{ audio_url, ingredient_sheet, receipt_id } |
创作档 | 按字符+时长双重计量 |
generate-status |
GET | task_id |
{ status, progress, estimated_completion } |
创作档 | 免费 |
generate-history |
GET | profile_id, date_range |
[{ task_id, text, created_at, ingredient_sheet }] |
创作档（仅户主本人） | 免费 |
4. 市集（公开档样品库）
公开声音样品库——搜索免费，调用付费，声音主人参与分成。
| 接口名（slug） | 方法 | 输入 | 输出 | 授权档位 | 收费模式 |
|---|---|---|---|---|---|
marketplace-search |
GET | query, language, gender, age_range, style_tags |
[{ profile_id, public_label, sample_preview_url, price_per_use }] |
公开档 | 免费搜索，调用付费 |
marketplace-purchase |
POST | profile_id, purpose, usage_scope |
{ license_id, audio_url, ingredient_sheet, receipt_id } |
公开档+用途协议 | 按次付费，声音主人分成 |
marketplace-split-report |
GET | profile_id, date_range |
{ total_earnings, transactions } |
受限档（仅户主本人） | 免费 |
5. 账本调取
户主查全部回执；受限档需走"申请→批准→限时令牌"流程。
| 接口名（slug） | 方法 | 输入 | 输出 | 授权档位 | 收费模式 |
|---|---|---|---|---|---|
ledger-query |
GET | profile_id, event_type, date_range |
{ receipts, chain_valid } |
户主全量；受限档需令牌 | 户主免费；第三方按次 |
ledger-access-request |
POST | profile_id, requester_id, purpose, field_scope |
{ request_id, status: "PENDING" } |
受限档 | 免费提交 |
ledger-access-approve |
POST | request_id, token_ttl_seconds |
{ access_token, expires_at, allowed_fields } |
受限档（需批准） | 免费 |
🚧 计量与计费说明（即将发布）
各接口的详细计量规则、单价、免费额度、发票与结算周期将在后端实现阶段确定并公布。