Guide d’intégration · API

Mise à jour 2026-10-22

Appelez les outils en HTTPS avec une clé personnelle. Exécutez ces exemples dans l’ordre pour séparer la voix d’un MP3. Avant de changer d’outil, consultez ses paramètres et limites.

Nécessite Bash, curl 7.76+ et jq. Exécutez dans le même terminal.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Préparation et authentification

Créez une clé Lecture et exécution et envoyez Authorization: Bearer. Aucun Cookie de connexion, CSRF ni renouvellement de session du navigateur n’est nécessaire.

Les listes vides autorisent tous les outils et IP ; les règles du compte restent applicables. Budgets en UTC. Un transfert interrompu conserve son allocation. La nouvelle clé conserve les droits et la date d’expiration. Mettez les scripts à jour pendant les cinq minutes de transition maximales.

Créer une clé →

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"

02Envoyer un fichier

Demandez une URL signée puis envoyez le fichier original par PUT. Indiquez la taille réelle en octets et le même 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)"

Les URL signées durent généralement 15 minutes. N’envoyez pas la clé au PUT. Exemple en PUT simple ; avec multipart_supported=true, envoyez les parts puis upload/multipart/complete, ou abort en cas d’échec.

03Confirmer le prix et déposer

Lisez le prix de base du modèle ou outil, transmettez-le tel quel dans pricing et conservez task_id. Quantité et prétraitement suivent les tarifs de l’outil ; RVC nécessite d’abord analyse et devis d’entraînement.

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)

Le devis ne réserve pas de crédits. En cas de 409 PRICE_CHANGED, relisez et confirmez le prix. Génération musicale et reprise de référence nécessitent les paramètres des modèles choisis.

Conservez request-key.txt et request.json. Le même compte, Idempotency-Key et contenu identique renvoient la tâche initiale. Utilisez une nouvelle clé pour une nouvelle tâche ; vérifiez tout envoi incertain avant de relancer.

04Suivre la progression

Interrogez toutes les 3 secondes. Téléchargez après completed ; failed, timeout et cancelled sont terminaux. Après deux heures, seule l’attente s’arrête, pas la tâche.

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élécharger les résultats

Encodez le s3_key de output_files dans l’URL et utilisez-le comme fileId. proxy=true diffuse l’original depuis la même origine avec contrôle de propriété.

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

Les requêtes Bearer vers /api/v1/tasks/{taskId}/download renvoient directement le fichier original ou un ZIP. La durée de conservation s’applique ; la clé API n’est jamais transmise au stockage.

Erreurs et reprise

Examinez le statut HTTP et les error.code, message, details d’origine. Ne vous fiez pas seulement au texte et n’enregistrez pas une erreur comme résultat.

400	Vérifiez fichier, paramètres et JSON.
401	Clé absente, invalide, expirée ou révoquée.
402	Crédits insuffisants ; vérifiez le solde.
403	Lecture seule ou accès refusé.
404	Ressource absente ou appartenant à un autre compte.
409	Prix ou état modifié ; lisez le code.
413	Fichier supérieur à la limite de l’outil.
429	Trop de requêtes ; respectez Retry-After.
503	Maintenance ou panne temporaire ; gardez l’erreur et vérifiez plus tard.

Pour 429, respectez Retry-After ou un délai progressif borné. Ne réessayez que les lectures sûres. Si une demande d’envoi ou un POST de tâche expire, vérifiez d’abord son résultat sans recréer aveuglément.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Cette clé API ne peut pas effectuer cette action.",
    "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

Conservez task_id dans task.json et reprenez le suivi. Vérifiez les dépôts récents dans la liste ; appelez cancel uniquement pour arrêter la tâche.

Référence API

Les chemins utilisent /api/v1 sur le même site. Les clés accèdent à vos ressources, pas à la gestion du compte, à la création de clés, à l’administration ou aux rappels internes.

GET	`/api/v1/tools`	Catalogue d’outils
GET	`/api/v1/tools/{toolId}`	Paramètres et limites
GET	`/api/v1/credits/balance`	Solde de crédits
POST	`/api/v1/tools/{toolId}/quote`	Prix actuel
POST	`/api/v1/tools/{toolId}/upload`	Envoyer un fichier
POST	`/api/v1/tools/{toolId}/tasks`	Confirmer le prix et déposer
GET	`/api/v1/tasks/{taskId}`	Suivre la progression
GET	`/api/v1/tasks`	Vos tâches
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Télécharger les résultats
POST	`/api/v1/tasks/{taskId}/cancel`	Annuler votre tâche

midi-converter et midi-lyrics fonctionnent dans le navigateur sans API d’envoi ou d’exécution serveur. Les détails des autres outils définissent disponibilité, formats, taille et paramètres.

Catalogue d’outils