Integrationsanleitung · API

Aktualisiert 2026-10-22

Rufen Sie Werkzeuge mit einem persönlichen API-Schlüssel über HTTPS auf. Die aufeinanderfolgenden Beispiele trennen Gesang aus einer MP3-Datei. Prüfen Sie vor einem Werkzeugwechsel dessen Parameter und Eingabegrenzen.

Bash, curl 7.76+ und jq erforderlich. Schritte im selben Terminal ausführen.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Vorbereitung und Anmeldung

Erstellen Sie einen Schlüssel mit Lesen und Ausführen und senden Sie Authorization: Bearer. Login-Cookies, CSRF und Sitzungserneuerung sind nicht nötig.

Leere Tool- und IP-Listen erlauben alle; Kontorichtlinien gelten weiterhin. Budgets richten sich nach UTC. Abgebrochene Übertragungen behalten ihre Zuteilung. Der neue Schlüssel übernimmt Rechte und Ablaufdatum. Aktualisieren Sie Skripte während der höchstens fünfminütigen Übergangszeit.

Schlüssel erstellen →

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"

02Datei hochladen

Signierte Upload-URL anfordern, dann die Originaldatei per PUT senden. Tatsächliche Bytezahl und identischen Content-Type verwenden.

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

Upload-URLs gelten meist 15 Minuten. Beim PUT keinen API-Schlüssel senden. Das Beispiel nutzt einen PUT. Bei multipart_supported=true alle parts hochladen und upload/multipart/complete aufrufen; bei Fehlern abort.

03Preis bestätigen und einreichen

Rufen Sie den Basispreis des gewählten Werkzeugs/Modells ab, senden Sie ihn unverändert als pricing und speichern Sie task_id. Mengen und Vorverarbeitung folgen den Werkzeugtarifen; RVC-Training benötigt vorher Analyse und Trainingsangebot.

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)

Ein Angebot reserviert kein Guthaben. Bei 409 PRICE_CHANGED Preis neu abrufen und bestätigen. Musikgenerierung und Referenz-Cover benötigen die Parameter der gewählten Modelle.

Bewahren Sie request-key.txt und request.json auf. Gleiches Konto, Idempotency-Key und identischer Inhalt geben die ursprüngliche Aufgabe zurück. Für neue Aufgaben neue Schlüssel verwenden; unklare Übermittlungen zuerst abgleichen.

04Fortschritt abfragen

Alle 3 Sekunden abfragen. Download erst bei completed; failed, timeout und cancelled sind Endzustände. Nach zwei Stunden endet nur das Warten, nicht die Aufgabe.

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

05Ergebnisse herunterladen

Verwenden Sie den URL-kodierten s3_key aus output_files als fileId. proxy=true überträgt die Originaldatei von derselben Origin mit Eigentumsprüfung.

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-Anfragen an /api/v1/tasks/{taskId}/download liefern Originaldateien oder ZIP direkt. Aufbewahrungsfristen gelten; der API-Schlüssel wird nie an den Objektspeicher weitergegeben.

Fehler und Wiederaufnahme

HTTP-Status und ursprüngliche error.code, message und details prüfen. Nicht nur auf den Meldungstext vertrauen und Fehler nicht als Ergebnisdatei speichern.

400	Datei, Parameter und JSON prüfen.
401	Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
402	Guthaben unzureichend; Saldo prüfen.
403	Nur Leseberechtigung oder kein Zugriff.
404	Ressource fehlt oder gehört einem anderen Konto.
409	Preis oder Status geändert; Fehlercode prüfen.
413	Datei überschreitet die Werkzeuggrenze.
429	Zu viele Anfragen; Retry-After beachten.
503	Wartung oder vorübergehender Ausfall; Fehler sichern und später prüfen.

Bei 429 Retry-After beachten, sonst begrenzt verzögern. Nur sichere Lesevorgänge wiederholen. Nach Timeout einer Upload-Anforderung oder Aufgaben-POST zuerst das ursprüngliche Ergebnis prüfen; keine blinde Neuerstellung.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Dieser API-Schlüssel darf diese Aktion nicht ausführen.",
    "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 aus task.json aufbewahren und bei der Statusabfrage fortsetzen. Neue Einreichungen in der Aufgabenliste prüfen; cancel nur zum beabsichtigten Stoppen aufrufen.

API-Referenz

Alle Pfade verwenden /api/v1 derselben Website. Schlüssel gelten nur für eigene Ressourcen, nicht für Kontoverwaltung, Schlüsselerstellung, Admin oder interne Rückrufe.

GET	`/api/v1/tools`	Werkzeugkatalog
GET	`/api/v1/tools/{toolId}`	Parameter und Eingabegrenzen
GET	`/api/v1/credits/balance`	Kontoguthaben
POST	`/api/v1/tools/{toolId}/quote`	Aktueller Preis
POST	`/api/v1/tools/{toolId}/upload`	Datei hochladen
POST	`/api/v1/tools/{toolId}/tasks`	Preis bestätigen und einreichen
GET	`/api/v1/tasks/{taskId}`	Fortschritt abfragen
GET	`/api/v1/tasks`	Eigene Aufgaben
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Ergebnisse herunterladen
POST	`/api/v1/tasks/{taskId}/cancel`	Eigene Aufgabe abbrechen

midi-converter und midi-lyrics laufen lokal im Browser ohne serverseitige Upload- oder Ausführungs-API. Für andere Werkzeuge gelten Verfügbarkeit, Formate, Größe und Parameter des Detail-Endpunkts.

Werkzeugkatalog