คู่มือเชื่อมต่อ · API
อัพเดท 2026-10-22
เรียกเครื่องมือผ่าน HTTPS ด้วยคีย์ส่วนตัว ทำตัวอย่างตามลำดับเพื่อแยกเสียงร้องจาก MP3 ก่อนเปลี่ยนเครื่องมือให้ตรวจพารามิเตอร์และข้อจำกัด
ต้องใช้ Bash, curl 7.76+ และ jq เรียกตามลำดับในเทอร์มินัลเดียวกัน
01เตรียมและยืนยันตัวตน
สร้างคีย์อ่านและเรียกใช้งาน แล้วส่ง Authorization: Bearer ไม่ต้องใช้ Cookie เข้าสู่ระบบ CSRF หรือรีเฟรชเซสชันเบราว์เซอร์
รายการว่างหมายถึงอนุญาตทุกเครื่องมือและ IP โดยยังอยู่ภายใต้นโยบายบัญชี งบประมาณใช้เวลา UTC การโอนที่ขัดข้องยังคงใช้ปริมาณที่อนุญาตไว้ คีย์ใหม่ใช้สิทธิ์และวันหมดอายุเดิม โปรดอัปเดตสคริปต์ภายในช่วงเปลี่ยนผ่านไม่เกินห้านาที
สร้างคีย์ →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 เดียวกัน
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 ตัวอย่างใช้ PUT ครั้งเดียว หากตั้ง multipart_supported=true ให้อัปโหลด parts แล้วเรียก upload/multipart/complete หรือ abort เมื่อผิดพลาด
03ยืนยันราคาและส่งงาน
อ่านราคาพื้นฐานของเครื่องมือหรือโมเดล ส่งค่าเดิมใน 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 และเนื้อหาเดิมจะได้งานเดิมกลับมา งานใหม่ต้องใช้คีย์ใหม่ หากไม่ทราบผลให้ตรวจสอบคำขอเดิมก่อนรันอีกครั้ง
04ตรวจความคืบหน้า
ตรวจทุก 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)" = completed05ดาวน์โหลดผล
เข้ารหัส s3_key จาก output_files สำหรับ 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 ต่อไปยังพื้นที่เก็บวัตถุ
ข้อผิดพลาดและการกู้คืน
อ่านสถานะ 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_id ใน task.json และเริ่มต่อจากตรวจสถานะ ดูงานที่ส่งล่าสุดในรายการ เรียก cancel เฉพาะเมื่อต้องการหยุด
อ้างอิง API
เส้นทางใช้ /api/v1 ของเว็บไซต์เดียวกัน คีย์เข้าถึงเฉพาะทรัพยากรของตน ไม่ใช้จัดการบัญชี สร้างคีย์ ผู้ดูแล หรือ callback ภายใน
| 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 อัปโหลดหรือประมวลผลบนเซิร์ฟเวอร์ ดูสถานะ รูปแบบ ขนาด และพารามิเตอร์ของเครื่องมืออื่นในรายละเอียด