Hướng dẫn tích hợp · API

Cập nhật 2026-10-22

Gọi công cụ qua HTTPS bằng khóa cá nhân. Chạy ví dụ theo thứ tự để tách giọng từ MP3. Đọc tham số và giới hạn đầu vào trước khi đổi công cụ.

Cần Bash, curl 7.76+ và jq. Chạy trong cùng cửa sổ dòng lệnh.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Chuẩn bị và xác thực

Tạo khóa Đọc và thực thi rồi gửi Authorization: Bearer. Không cần Cookie đăng nhập, CSRF hoặc làm mới phiên trình duyệt.

Danh sách trống cho phép mọi công cụ và IP; chính sách tài khoản vẫn áp dụng. Hạn mức tính theo UTC. Truyền bị ngắt vẫn chiếm dung lượng được cấp. Khóa mới giữ nguyên quyền và hạn dùng. Cập nhật tập lệnh trong thời gian chuyển tiếp tối đa năm phút.

Tạo khóa →

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"

02Tải tệp lên

Xin URL có chữ ký rồi PUT tệp gốc. Dùng số byte thực và cùng 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 thường có hiệu lực 15 phút. Không gửi khóa API khi PUT. Ví dụ dùng PUT đơn; với multipart_supported=true hãy gửi parts rồi gọi upload/multipart/complete, hoặc abort khi lỗi.

03Xác nhận giá và gửi

Đọc giá cơ bản của công cụ/mô hình, gửi nguyên dạng trong pricing và lưu task_id. Số lượng và tiền xử lý vẫn theo quy tắc giá công cụ; RVC cần phân tích và báo giá huấn luyện trước.

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)

Báo giá không giữ tín dụng. Gặp 409 PRICE_CHANGED hãy đọc và xác nhận giá mới. Tạo nhạc và cover tham chiếu cần tham số của mô hình đã chọn.

Giữ request-key.txt và request.json. Cùng tài khoản, Idempotency-Key và nội dung giống hệt sẽ trả về tác vụ gốc. Dùng khóa mới cho tác vụ mới; kiểm tra yêu cầu chưa rõ kết quả trước khi chạy lại.

04Kiểm tra tiến độ

Kiểm tra mỗi 3 giây. Tải khi completed; failed, timeout, cancelled là trạng thái kết thúc. Sau hai giờ chỉ dừng chờ, không hủy tác vụ.

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

05Tải kết quả

Mã hóa s3_key trong output_files cho URL và dùng làm fileId. proxy=true truyền bản gốc từ cùng nguồn với kiểm tra chủ sở hữu.

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

Yêu cầu Bearer đến /api/v1/tasks/{taskId}/download trả trực tiếp tệp gốc hoặc ZIP. Áp dụng thời hạn lưu giữ; khóa API không được chuyển đến kho đối tượng.

Lỗi và khôi phục

Đọc HTTP và error.code, message, details gốc. Không chỉ dựa vào lời thông báo hoặc lưu lỗi thành tệp kết quả.

400	Kiểm tra tệp, tham số và JSON.
401	Khóa thiếu, sai, hết hạn hoặc đã thu hồi.
402	Không đủ tín dụng; kiểm tra số dư.
403	Chỉ đọc hoặc không có quyền truy cập.
404	Tài nguyên không tồn tại hoặc thuộc tài khoản khác.
409	Giá hoặc trạng thái thay đổi; đọc mã lỗi.
413	Tệp vượt giới hạn công cụ.
429	Quá nhiều yêu cầu; chờ Retry-After.
503	Bảo trì hoặc lỗi tạm thời; giữ lỗi và kiểm tra sau.

Với 429 chờ Retry-After hoặc tăng thời gian chờ có giới hạn. Chỉ thử lại thao tác đọc an toàn. POST tải lên hay gửi tác vụ hết thời gian thì kiểm tra kết quả cũ trước, không tạo lặp.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Khóa API này không được thực hiện thao tác.",
    "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

Lưu task_id trong task.json và tiếp tục từ kiểm tra trạng thái. Xem tác vụ gửi gần đây trong danh sách; chỉ gọi cancel khi muốn dừng.

Tham chiếu API

Đường dẫn dùng /api/v1 cùng trang. Khóa chỉ truy cập tài nguyên của bạn, không quản lý tài khoản, tạo khóa, quản trị hay callback nội bộ.

GET	`/api/v1/tools`	Danh mục công cụ
GET	`/api/v1/tools/{toolId}`	Tham số và giới hạn
GET	`/api/v1/credits/balance`	Số dư tín dụng
POST	`/api/v1/tools/{toolId}/quote`	Giá hiện tại
POST	`/api/v1/tools/{toolId}/upload`	Tải tệp lên
POST	`/api/v1/tools/{toolId}/tasks`	Xác nhận giá và gửi
GET	`/api/v1/tasks/{taskId}`	Kiểm tra tiến độ
GET	`/api/v1/tasks`	Danh sách tác vụ của bạn
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Tải kết quả
POST	`/api/v1/tasks/{taskId}/cancel`	Hủy tác vụ của bạn

midi-converter và midi-lyrics chạy trong trình duyệt, không có API tải lên hay thực thi trên máy chủ. Chi tiết các công cụ khác quy định trạng thái, định dạng, kích thước và tham số.

Danh mục công cụ