Οδηγός ενσωμάτωσης · API

ΕΠΙΚΑΙΡΟΠΟΙΗΜΕΝΟ 2026-10-22

Καλέστε εργαλεία μέσω HTTPS με προσωπικό κλειδί. Εκτελέστε τα παραδείγματα διαδοχικά για διαχωρισμό φωνής MP3. Πριν αλλάξετε εργαλείο ελέγξτε παραμέτρους και όρια.

Απαιτούνται Bash, curl 7.76+ και jq. Ίδιο τερματικό για όλα τα βήματα.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Ρύθμιση και ταυτοποίηση

Δημιουργήστε κλειδί Ανάγνωση και εκτέλεση και στείλτε Authorization: Bearer. Δεν χρειάζονται Cookie, CSRF ή ανανέωση συνεδρίας browser.

Οι κενές λίστες επιτρέπουν όλα τα εργαλεία και IP· ισχύουν οι κανόνες λογαριασμού. Όρια σε UTC. Οι διακοπείσες μεταφορές διατηρούν την κατανομή τους. Το νέο κλειδί διατηρεί δικαιώματα και λήξη. Ενημερώστε τα σενάρια στη μεταβατική περίοδο έως πέντε λεπτών.

Δημιουργία κλειδιού →

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. Χρησιμοποιήστε τα πραγματικά byte και ίδιο 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. Το παράδειγμα έχει ένα 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 διαβάστε και επιβεβαιώστε νέα τιμή. Μουσική δημιουργία και cover αναφοράς απαιτούν παραμέτρους επιλεγμένων μοντέλων.

Κρατήστε τα request-key.txt και request.json. Ίδιος λογαριασμός, Idempotency-Key και πανομοιότυπο περιεχόμενο επιστρέφουν την αρχική εργασία. Για νέα εργασία χρησιμοποιήστε νέο κλειδί· ελέγξτε πρώτα κάθε αβέβαιη υποβολή.

04Έλεγχος προόδου

Ελέγχετε κάθε 3 δευτερόλεπτα. Λήψη στο completed· failed, timeout, cancelled είναι τελικές καταστάσεις. Μετά δύο ώρες σταματά η αναμονή, όχι η εργασία.

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Λήψη αποτελεσμάτων

Κωδικοποιήστε το s3_key του output_files για 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 ή περιορισμένη αυξανόμενη καθυστέρηση. Επαναλάβετε μόνο ασφαλείς αναγνώσεις. Μετά από timeout POST ελέγξτε το αρχικό αποτέλεσμα πριν δημιουργήσετε ξανά.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Αυτό το κλειδί API δεν επιτρέπει την ενέργεια.",
    "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_id στο task.json και συνεχίστε τον έλεγχο. Δείτε πρόσφατες υποβολές στη λίστα· καλέστε cancel μόνο για διακοπή.

Αναφορά API

Όλες οι διαδρομές είναι /api/v1 στον ίδιο ιστότοπο. Τα κλειδιά αφορούν δικούς σας πόρους, όχι λογαριασμό, δημιουργία κλειδιών, admin ή εσωτερικά 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 εκτελούνται στον browser χωρίς API μεταφόρτωσης ή εκτέλεσης διακομιστή. Για άλλα εργαλεία, οι λεπτομέρειες ορίζουν κατάσταση, μορφές, μέγεθος και παραμέτρους.

Κατάλογος εργαλείων