導入ガイド · API

更新 2026-10-22

個人 API キーで HTTPS 経由のツールを利用します。MP3 のボーカル分離を例に順番に実行します。別のツールでは先にパラメーターと入力制限を確認してください。

Bash、curl 7.76+、jq が必要です。同じ端末で順番に実行してください。

01準備と認証

アカウントで「読み取りと実行」キーを作成し Authorization: Bearer を送信します。Cookie、CSRF、ブラウザーセッションの更新は不要です。

ツールと IP が空欄なら制限なしですが、アカウント設定は適用されます。日/月の上限は UTC 基準です。転送を中断しても許可量を消費します。新しいキーは権限と元の有効期限を引き継ぎます。古いキーの最長 5 分間の猶予内にスクリプトを更新してください。

キーを作成 →

Bash / curl

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"

02ファイルをアップロード

署名付き URL を取得して元ファイルを PUT します。実際のバイト数と同じ Content-Type を指定してください。

Bash / curl

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)"

署名付き URL は通常 15 分間有効です。PUT 先に API キーを送らないでください。例は単一 PUT です。multipart_supported=true の場合は parts を送って upload/multipart/complete、失敗時は abort を呼び出します。

03料金確認と送信

選択ツール・モデルの基本料金を取得し、そのまま pricing に送って task_id を保存します。数量や前処理はツールの料金規則に従います。RVC 学習には先に分析と学習見積もりが必要です。

Bash / curl

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、本文で再送すると元のタスクを返します。新規タスクには新しいキーを使い、結果不明の場合は元の送信を確認してください。

04進行状況を確認

3 秒ごとに確認します。completed でダウンロードでき、failed、timeout、cancelled は終了状態です。2 時間で待機を停止してもタスクは取り消されません。

Bash / curl

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

05結果をダウンロード

output_files の s3_key を URL エンコードして fileId に使用します。proxy=true は所有者を確認して同一オリジンから元ファイルを配信します。

Bash / curl

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 キーはストレージに転送されません。

エラーと復旧

HTTP 状態と元の error.code、message、details を確認します。文言だけに依存したりエラーを結果ファイルとして保存したりしないでください。

400	ファイル、パラメーター、JSON を確認。
401	キーなし、無効、期限切れ、失効済み。
402	クレジット不足。残高を確認。
403	読み取り専用またはアクセス権限なし。
404	リソースが存在しないか別アカウントの所有です。
409	料金やタスク状態が変更。エラーコードを確認。
413	ファイルサイズ上限を超過。
429	リクエスト過多。Retry-After に従う。
503	メンテナンスまたは一時障害。エラーを保持して後で確認。

429 は Retry-After に従い、なければ上限付きで待機します。再試行は安全な読み取りのみ。アップロード申請やタスク POST のタイムアウト時は元の結果を確認し、重複作成を避けてください。

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "この操作を実行する権限がありません。",
    "details": []
  }
}

Bash / curl

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 一覧

同一サイトの /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 を確認してください。

ツール一覧