如何通过 hiapi API 使用 lyria-3-pro：curl、Python 与可运行的请求示例

lyria-3-pro 是一个通过 hiapi API 提供的音乐生成模型：发送文本提示，就能得到一段完整的音轨。本指南会带你走一遍真正能返回 taskId 的请求流程，说明完整的（非常简短的）输入 schema，以及在你脱离一次性测试后所需的生产环境细节。

你需要准备

• 一个 hiapi API key。可从控制台获取——key 以 sk- 开头。
• curl 或 Python 的 requests。无需 SDK；hiapi 使用标准 REST。

lyria-3-pro 运行在 hiapi 的统一异步任务 API 上：你 POST 一个任务，立即拿回 taskId，然后轮询结果，或在音轨就绪时接收回调。

最小可运行示例

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-pro",
    "input": {
      "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood"
    }
  }'

正常响应会在音轨真正渲染完成之前立即返回：

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" }
}

2. 轮询结果

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M0T17T7RERV481QJC3DRZCRS" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

首次轮询前等待几秒，之后每 3–5 秒检查一次。status 会经过 archiving 等中间状态，最后进入终止状态：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS",
    "model": "lyria-3-pro",
    "status": "success",
    "created": 1787580115,
    "completed": 1787580157,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T17T7RERV481QJC3DRZCRS-0.mp3",
        "expireAt": 1788184956
      }
    ]
  }
}

请尽快下载 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-pro",
    "input": {
        "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood",
    },
}

create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]

while True:
    time.sleep(3)
    detail = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = detail["data"]["status"]
    if status == "success":
        print(detail["data"]["output"][0]["url"])
        break
    if status == "fail":
        raise RuntimeError(detail["data"]["error"])

完整输入 schema

input 恰好接受两个字段——此列表之外的任何内容都会被拒绝，并返回 400 INVALID_REQUEST：

字段	类型	是否必填	说明
prompt	string	是	描述流派、配器、情绪和速度——越具体，结果越一致。
seed	integer	否	最小值为 0。用相同 prompt 复用同一 seed，可获得更可复现的结果。

prompt 是必填的——省略它，任务根本不会被创建：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

发送其他任何字段——duration、negative_prompt、sample_count 以及某些其他音乐模型接受的类似字段——请求会被直接拒绝：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'negative_prompt' not allowed"}

输出音轨的时长由模型本身固定；没有 duration 参数可用于配置它。

生产环境注意事项

回调优于轮询。 除快速测试外，请传入顶层 callback，而不是在循环中轮询：

{
  "model": "lyria-3-pro",
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" },
  "input": { "prompt": "..." }
}

当任务到达终止状态（success 或 fail）时，hiapi 会向 callback.url 发送一次 POST——无需保持轮询循环开启。仍应保留轮询作为兜底，以防回调投递失败。

幂等性。 如果调用方可能重试同一请求，请发送 Idempotency-Key 请求头（最多 255 字节）——同一账户使用相同 key 的重试会返回原始 taskId，而不会创建（并计费）重复音轨。

将输出保留超过 7 天。 输出存储默认是 temp（约 7 天）。创建时设置顶层 "storage": "persistent" 可长期保留音轨（按大小计费），或之后再提升 temp 输出。

错误处理。 错误或未授权的 key 会返回 HTTP 401：

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. Please check permissions or use another key.","type":"hiapi_error"}}

格式错误的输入会返回 400，并带有 error_code: INVALID_REQUEST（如上所示）；余额不足返回 402；非 JSON 的 Content-Type 返回 415。如果遇到间歇性 503，请退避重试——它表示平台暂时不可用，而非你的请求有误。

lyria-3-pro（以及平台上其他所有模型）的价格列在 hiapi 定价页，而非硬编码在此处，因为档位可能变化。

相关资源

• lyria-3-pro 模型参考——该模型的定价与演练场。
• 创建任务 / 获取任务详情（统一异步 API）——hiapi 上每个模型使用的共享请求/响应契约。
• minimax-music-3 API：curl 与 Python 指南——另一个文本转音乐模型，可用于比较输出风格。
• 如何使用 MiniMax Music API（minimax-music-1.5）——更早的 MiniMax 音乐生成模型，适合进行成本/质量比较。

常见问题

可以设置生成音轨的时长吗？ 不能。lyria-3-pro 的 input schema 只接受 prompt 和 seed——没有 duration 字段，音轨时长由模型自行决定。

lyria-3-pro 支持负面提示词或风格参考音频吗？ 不支持。与平台上其他一些模型不同，lyria-3-pro 的 schema 严格仅限 prompt 和 seed；发送 negative_prompt 或任何参考音频字段会返回 400 INVALID_REQUEST。

输出文件是什么格式？ MP3，以 output[0].url 返回，type 为 "audio"。该 URL 是临时链接，除非设置 "storage": "persistent"，否则会按 output[0].expireAt 过期。

如何获得可复现的结果？ 使用相同的 prompt 并传入相同的 seed（非负整数）。省略 seed 时，每次调用都可能产生不同的结果。

调试持续返回 400 的请求最快的方法是什么？ 阅读 message——它会指出具体缺失或无效的字段。该 schema 很严格：发送此模型不接受的字段（例如平台上其他音乐模型确实接受的 duration）会返回 400，并带有 "additional properties not allowed" 错误。