🔌 开放 API

把钢琴演奏的音频或视频转成 MIDI、MusicXML、刻印五线谱(SVG/PDF)、和弦与节拍。密钥挂在你的登录账号下;只处理你自己托管或上传、并拥有权利的内容。

API 密钥

快速开始

基址

https://piano.ai2.fun/v1

1 · 提交你托管的媒体 URL(或直接上传文件)

curl -X POST https://piano.ai2.fun/v1/transcriptions \
  -H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \
  -d '{"url":"https://cdn.example.com/perf.mp4","name":"Nocturne","style":"classical","callback_url":"https://example.com/hook"}'

# 或上传文件(≤512MB;audio/* 或 video/*)
curl -X POST https://piano.ai2.fun/v1/transcriptions \
  -H "Authorization: Bearer sk_live_…" -H "Content-Type: video/mp4" \
  -H "X-Filename: perf.mp4" -H "X-Song-Name: Nocturne" --data-binary @perf.mp4

2 · 轮询状态(或等 webhook)

curl https://piano.ai2.fun/v1/transcriptions/<id> -H "Authorization: Bearer sk_live_…"
# → {"id":"…","status":"queued|running|ready|error","stage":"…","key":"E minor","bpm":107,
#    "assets":{"transkun_mid":"…","transkun_musicxml":"…","score_sheet_pdf":"…","sheet_svg_pages":[…],"chords_json":"…","beats_json":"…"}}

3 · 下载产物

curl -L https://piano.ai2.fun/v1/transcriptions/<id>/assets/score_sheet.pdf -H "Authorization: Bearer sk_live_…" -o sheet.pdf

Webhook

任务完成或失败时向 callback_url POST 一次 Job 对象;失败按指数退避最多重试 6 次。请求头 X-Piano-Signature: t=<unix>,v1=<hex>,其中 v1 = HMAC-SHA256(webhook_secret, "<t>.<body>")。

import hmac, hashlib
def verify(secret, sig_header, body: bytes):
    parts = dict(p.split('=', 1) for p in sig_header.split(','))
    mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts['v1'])

限制与规则

每密钥每分钟 60 次调用;默认每月 60 分钟音频(按源文件时长计)。更高额度请联系我们。
只接受你自己托管的媒体 URL 或直接上传;B站、YouTube、小红书、抖音等第三方平台链接一律拒绝(422)。
提交即表示你对该内容拥有处理权利;产物中的乐谱署名默认保留。
错误格式:{"error":{"code","message"}};401 未授权 · 402 额度用尽 · 422 内容不允许 · 429 限速。
OpenAPI JSON