教程
如何通过 hiapi API 使用 lyria-3.5：curl、Python 与一个可用的请求
lyria-3.5 是 hiapi 的文本生成音乐模型：发送一段音乐描述、歌词或两者兼有，即可获得一首成品音轨——还可选填标题、节奏引导和时长控制。本指南将完整讲解输入 schema、一个能返回真实音轨的请求，以及一次性测试之后投产所需的细节。
你需要准备什么
- 一个 hiapi API key。可在 dashboard 获取——key 以
sk-开头。 curl或 Python 的requests。无需 SDK；hiapi 使用纯 REST。
lyria-3.5 运行在 hiapi 的统一异步任务 API 上：你用 POST 提交一个任务，立即拿回一个 taskId，然后轮询结果，或在音轨就绪时接收回调。
完整输入 schema
lyria-3.5 接受的远不止一个裸 prompt。除你必须至少提供 prompt 或 lyrics 之一外，所有字段都是可选的：
| 字段 | 类型 | 说明 |
|---|---|---|
prompt |
string | 流派、乐器、情绪、人声、歌曲结构。提供 prompt 或 lyrics。 |
lyrics |
string | 每行一句。段落标签——[Intro]、[Verse]、[Chorus]、[Bridge]、[Outro]——各自独占一行，后面跟歌词。重复段落用 [Verse 1]、[Verse 2] 编号。 |
title |
string | 生成歌曲的标题。 |
bpm |
string | 节奏引导，须为数字字符串，例如 "90"。 |
length |
integer | 请求的时长（秒），1–240。用于引导长度；实际时长可能不同。省略则不指定。 |
seed |
string | 数字字符串种子，例如 "00123"。即使 seed 相同，也不保证得到完全相同的音频。 |
有两点需要提前提醒：bpm 和 seed 是字符串而非数字——发送 "90"，而不是 90，否则 API 会返回 400（got number, want string）。而且 schema 是严格的：任何不在上表中的字段（duration、style、genre、negative_prompt 等）都会以 additional properties '...' not allowed 返回 400。
最小可用示例
1. 创建任务
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer sk-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "lyria-3.5",
"input": {
"prompt": "Warm instrumental indie folk, fingerpicked acoustic guitar, soft brushed drums, quiet morning",
"bpm": "90",
"length": 30
}
}'
正常响应会在音轨实际渲染完成之前立即返回：
{
"code": 200,
"message": "success",
"data": { "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2" }
}
2. 轮询结果
curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2" \
-H "Authorization: Bearer sk-YOUR_API_KEY"
首次轮询前先等几秒，之后每 3–5 秒检查一次。status 会先经过 handling，然后进入终态。以下是上述请求在大约 100 秒之后的实际响应：
{
"code": 200,
"data": {
"taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2",
"model": "lyria-3.5",
"status": "success",
"created": 1789437730,
"completed": 1789437829,
"output": [
{
"type": "audio",
"url": "https://temp.hiapi.ai/7c6ttvrbpt/01M2HCSKAP77MTH1ANKQXE1DT2-0.m4a",
"expireAt": 1790042629
}
]
}
}
注意输出容器格式可能因请求而异（这里是 .m4a；hiapi 上的其他音乐模型返回 .mp3）——应读取 output[0].type/URL，而不是硬编码扩展名。请及时下载 output[0].url：默认的 temp 存储层大约 7 天后过期（expireAt 是 Unix 时间戳）。失败时，status 为 fail，data.error 中会包含 { code, message }，而不是 output。
3. 用 Python 发送歌词驱动的请求
import time
import requests
API_KEY = "sk-YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
payload = {
"model": "lyria-3.5",
"input": {
"title": "Carry the Morning",
"lyrics": (
"[Verse 1]\n"
"Light through the window, coffee still warm\n"
"[Chorus]\n"
"Carry the morning, carry it slow\n"
),
"bpm": "96",
"length": 45,
},
}
create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]
status = None
while status not in ("success", "fail"):
time.sleep(4)
poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
status = poll["data"]["status"]
if status == "success":
print(poll["data"]["output"][0]["url"])
else:
print(poll["data"]["error"])
根据你需要纯音乐还是人声音轨，把 lyrics 换成 prompt（或两者都发送）。
生产环境注意事项
- 用回调代替轮询。添加一个顶层
callback对象：{"url": "https://yourapp.com/hook", "when": "final"}。when只接受"final"——任务进入终态时你会收到一次调用，而不是进度更新。 - 幂等性。任务 API 不接受客户端提供的幂等键，因此要在应用层防止重试问题：收到
taskId后立即持久化，并在重试前检查任务状态，避免发出重复请求。 - 错误。API key 缺失或无效会返回 HTTP 401 和
error_code: "permission_denied"。违反 schema 会返回 HTTP 400 和error_code: "INVALID_REQUEST"，并在消息中指明出问题的字段——这有助于在进入生产前发现多余的duration或数字类型的bpm。 - 存储。成功轮询或收到回调后，立即将
output[0].url转移到你自己的存储中；不要依赖temp层超过其expireAt。
相关阅读
- lyria-3-pro API 教程——hiapi 的另一个 Lyria 模型，如果你不需要歌词或节奏控制，它的 schema 更简单，只需 prompt。
- MiniMax Music API 指南——hiapi 上的另一个文本生成音乐模型，有自己的一套歌词和采样选项。
- lyria-3.5 模型参考——权威的参数文档。
- hiapi 定价——当前各模型费率。
FAQ
我需要同时发送 prompt 和 lyrics 吗？不需要——API 只要求两者至少提供一个。只发 prompt 得到纯音乐音轨，只发 lyrics 得到完全由歌词驱动的音轨，或两者一起发。
lyria-3.5 返回什么音频格式？因请求而异——请检查 output[0].type 和 URL 的扩展名，不要假定是 .mp3 或 .m4a。
我能强制指定精确的节奏吗？bpm 是引导性的，不是硬性约束，并且必须以字符串发送（"90"，而不是 90）。
生成的音轨可以有多长？length 接受 1–240 秒，但它只是引导模型，并不保证精确时长——请检查返回文件的实际运行时长。
相同的 seed 会让我两次得到相同的音轨吗？不会。seed 是数字字符串，用于微调生成结果，但 hiapi 的文档明确说明不保证音频完全相同。
如果我发送了无法识别的字段，比如 genre 或 duration，会怎样？schema 是严格的——你会收到 400 和 additional properties '<field>' not allowed，而不是该字段被静默忽略。
