串接指南 · API
更新於 2026-10-22
更新於 2026-10-22
以個人 API Key 透過 HTTPS 呼叫工具。以下範例依序示範 MP3 人聲分離；更換工具前請先讀取其參數與輸入限制。
需要 Bash、curl 7.76+、jq；於同一終端依序執行。
在帳戶建立「讀取與執行」金鑰。命令列傳送 Authorization: Bearer，不需登入 Cookie、CSRF 或定期更新網頁工作階段。
工具及 IP 留空表示不限，仍受帳戶政策約束。預算以 UTC 日/月計算，傳輸中斷仍占用授權量。 新金鑰沿用權限及原到期時間。舊金鑰最多再有效 5 分鐘，請及時更新指令碼。
建立金鑰 →jq() { command jq "$@" | tr -d '\r'; }
read -rsp 'TELKNET_API_KEY: ' TELKNET_API_KEY; printf '\n'
export TELKNET_API_KEY
BASE="${TELKNET_BASE_URL:-https://telknet.cc}"
TOOL="${TELKNET_TOOL:-music-vocal-split}"
FILE="${TELKNET_FILE:-sample.mp3}"
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/credits/balance" \
-H "Authorization: Bearer $TELKNET_API_KEY"先申請簽署上傳網址，再 PUT 原始檔案。檔案大小須為真實位元組數，Content-Type 必須一致。
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tools/$TOOL/upload" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
-H 'Content-Type: application/json' \
-d "$(jq -n --arg filename "$(basename "$FILE")" \
--argjson size "$(wc -c < "$FILE")" \
'{filename:$filename,content_type:"audio/mpeg",file_size:$size}')" \
-o upload.json || { cat upload.json >&2; exit 1; }
curl --connect-timeout 10 --max-time 1800 --fail-with-body --request PUT \
-H 'Content-Type: audio/mpeg' --upload-file "$FILE" \
"$(jq -r '.data.upload_url' upload.json)"簽署上傳網址通常有效 15 分鐘，PUT 時不要傳送 API Key。範例採單次 PUT；設定 multipart_supported=true 時須上傳 parts，再呼叫 upload/multipart/complete，失敗時呼叫 abort。
先讀取所選工具／模型的基礎價格，原樣放入 pricing，成功後儲存 task_id。數量、預分軌等參數仍按工具規則計費；RVC 訓練須先分析並取得訓練報價。
printf '{}' > params.json
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tools/$TOOL/quote" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
-H 'Content-Type: application/json' \
-d "$(jq -n --slurpfile params params.json '{params:$params[0]}')" \
-o quote.json || { cat quote.json >&2; exit 1; }
jq -n --arg tool "$TOOL" --arg key "$(jq -r '.data.s3_key' upload.json)" \
--slurpfile params params.json --slurpfile quote quote.json \
'{tool_id:$tool,file_key:$key,params:$params[0],pricing:$quote[0].data}' > request.json
REQUEST_KEY="$(date +%s)-$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n')"
printf '%s' "$REQUEST_KEY" > request-key.txt
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tools/$TOOL/tasks" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
-H "Idempotency-Key: $REQUEST_KEY" \
-H 'Content-Type: application/json' --data-binary @request.json -o task.json || { cat task.json >&2; exit 1; }
TASK=$(jq -r '.data.task_id' task.json)報價不預留點數。409 PRICE_CHANGED 時重新讀取並確認價格後才提交。音樂生成及參考翻唱須攜帶所選模型參數。
保留 request-key.txt 及 request.json。同帳戶以相同 Idempotency-Key 及相同請求內容重送時會回傳原任務。新任務使用新鍵；結果不明時先核對原提交。
每 3 秒查詢。completed 才能下載；failed、timeout、cancelled 為終態。範例等候最多兩小時，停止輪詢不會取消任務。
deadline=$((SECONDS + 7200))
while (( SECONDS < deadline )); do
curl --connect-timeout 10 --max-time 60 --fail-with-body "$BASE/api/v1/tasks/$TASK" \
-H "Authorization: Bearer $TELKNET_API_KEY" -o status.json || { cat status.json >&2; exit 1; }
status=$(jq -r '.data.status' status.json)
case "$status" in
completed) break ;;
failed|timeout|cancelled) cat status.json >&2; exit 1 ;;
pending|processing) sleep 3 ;;
*) cat status.json >&2; exit 1 ;;
esac
done
test "$(jq -r '.data.status' status.json)" = completed將 output_files 中的 s3_key 做 URL 編碼後作為 fileId。proxy=true 透過同源介面傳輸原檔並檢查任務歸屬。
mkdir -p results
jq -r '.data.output_files | to_entries[] | .key' status.json | while read -r INDEX; do
FILE_ID=$(jq -r --argjson i "$INDEX" '.data.output_files[$i].s3_key | @uri' status.json)
NAME=$(basename "$(jq -r --argjson i "$INDEX" '.data.output_files[$i].name' status.json)")
curl --connect-timeout 10 --max-time 7200 --fail-with-body "$BASE/api/v1/tasks/$TASK/files/$FILE_ID?proxy=true" \
-H "Authorization: Bearer $TELKNET_API_KEY" \
--output "results/$INDEX-$NAME.part" || exit 1
EXPECTED=$(jq -r --argjson i "$INDEX" '.data.output_files[$i].size_bytes' status.json)
test "$(wc -c < "results/$INDEX-$NAME.part")" -eq "$EXPECTED" || exit 1
mv "results/$INDEX-$NAME.part" "results/$INDEX-$NAME"
done攜帶 Bearer 請求 /api/v1/tasks/{taskId}/download 時直接回傳原檔或 ZIP。檔案遵循保留期限，API Key 不會轉送至物件儲存。
讀取 HTTP 狀態與原始 error.code、message、details。不要只依賴錯誤文字，也不要把錯誤回應存為結果檔案。
| 400 | 檢查檔案、參數及 JSON。 |
| 401 | 金鑰缺失、無效、到期或已撤銷。 |
| 402 | 點數不足，先檢查餘額。 |
| 403 | 唯讀金鑰不能執行，或無權存取資源。 |
| 404 | 工具、任務或檔案不存在，或不屬於此帳戶。 |
| 409 | 價格或任務狀態已變更，請讀取錯誤碼。 |
| 413 | 檔案超過工具大小限制。 |
| 429 | 請求過多，依 Retry-After 等候。 |
| 503 | 維護或服務暫不可用；保留錯誤並稍後查詢。 |
429 依 Retry-After 等候，缺少時使用有限退避。只重試安全讀取；上傳申請或提交 POST 網路逾時時，先核對原請求結果，不自動重建任務。
{
"ok": false,
"error": {
"code": "API_KEY_SCOPE",
"message": "此 API 金鑰無權執行該操作。",
"details": []
}
}HTTP_CODE=$(curl --connect-timeout 10 --max-time 60 --silent --show-error \
-H "Authorization: Bearer $TELKNET_API_KEY" \
--output response.json --dump-header response.headers --write-out '%{http_code}' \
"$BASE/api/v1/tasks/$TASK")
if [[ "$HTTP_CODE" != 2* ]]; then
cat response.json >&2
if [[ "$HTTP_CODE" == 429 ]]; then
awk 'tolower($1)=="retry-after:" {print $2}' response.headers
fi
exit 1
fi保留 task.json 的 task_id，從輪詢恢復。可用任務列表核對近期提交；確定要停止時才呼叫 cancel。
所有網址使用同站 /api/v1。金鑰僅可存取自己的業務資源，不能管理帳戶、建立金鑰或呼叫後台與內部回呼。
| GET | /api/v1/tools | 工具目錄 |
| GET | /api/v1/tools/{toolId} | 參數與輸入限制 |
| GET | /api/v1/credits/balance | 帳戶餘額 |
| POST | /api/v1/tools/{toolId}/quote | 目前價格 |
| POST | /api/v1/tools/{toolId}/upload | 上傳檔案 |
| POST | /api/v1/tools/{toolId}/tasks | 確認價格並提交 |
| GET | /api/v1/tasks/{taskId} | 查詢任務進度 |
| GET | /api/v1/tasks | 我的任務列表 |
| GET | /api/v1/tasks/{taskId}/files/{fileId}?proxy=true | 下載結果 |
| POST | /api/v1/tasks/{taskId}/cancel | 取消自己的任務 |
midi-converter 與 midi-lyrics 在瀏覽器本機執行，不支援伺服器上傳或任務 API。其他工具的狀態、格式、大小及參數以工具詳情為準。
music-yourmt3, music-yourmt3-ymt3-plus, music-yourmt3-yptf-single-nops, music-yourmt3-yptf-multi-ps, music-yourmt3-yptf-moe-multi-ps, music-miros, music-vocal-harmony-split, music-dry-vocal, music-vocal-split, music-four-stem, music-six-stem, music-drum-split, music-drum-split-drumsep-mdx23c-6, music-mega-53-stem, music-eight-stem, music-restoration, music-custom-stem, music-piano-transkun, music-piano-transkun-standard, music-piano-transkun-v2-aug, music-piano-aria, music-piano-bytedance-pedal, ai-rvc, zonos2-tts, midi-converter,
midi-lyrics