Entegrasyon kılavuzu · API

Güncellendi 2026-10-22

Kişisel anahtarla HTTPS üzerinden araç çağırın. MP3 vokal ayırma örneklerini sırayla çalıştırın. Aracı değiştirmeden önce parametre ve giriş sınırlarını okuyun.

Bash, curl 7.76+ ve jq gerekir. Aynı terminalde çalıştırın.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Hazırlık ve kimlik doğrulama

Okuma ve yürütme anahtarı oluşturup Authorization: Bearer gönderin. Oturum Cookie, CSRF veya tarayıcı oturumu yenilemesi gerekmez.

Boş listeler tüm araç ve IP’lere izin verir; hesap kuralları geçerliliğini korur. Bütçeler UTC’ye göredir. Kesilen aktarımlar ayrılan miktarı kullanır. Yeni anahtar izinleri ve son kullanma tarihini devralır. En fazla beş dakikalık geçiş süresinde betikleri güncelleyin.

Anahtar oluştur →

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"

02Dosya yükle

İmzalı URL isteyin, ardından özgün dosyayı PUT ile gönderin. Gerçek bayt sayısını ve aynı Content-Type değerini kullanın.

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 genellikle 15 dakika geçerlidir. PUT isteğine anahtar göndermeyin. Örnek tek PUT kullanır; multipart_supported=true için parts yükleyip upload/multipart/complete, hata durumunda abort çağırın.

03Fiyatı onayla ve gönder

Seçilen araç/modelin temel fiyatını alın, pricing olarak aynen gönderin ve task_id kaydedin. Adet ve ön işleme araç fiyatlarına tabidir; RVC eğitimi önce analiz ve eğitim teklifi gerektirir.

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)

Fiyat teklifi kredi ayırmaz. 409 PRICE_CHANGED için yeni fiyatı okuyup onaylayın. Müzik üretimi ve referans cover seçilen modellerin parametrelerini gerektirir.

request-key.txt ve request.json dosyalarını saklayın. Aynı hesap, Idempotency-Key ve aynı içerik asıl görevi döndürür. Yeni görev için yeni anahtar kullanın; sonucu belirsiz gönderimleri önce kontrol edin.

04İlerlemeyi sorgula

Her 3 saniyede sorgulayın. completed sonrası indirin; failed, timeout, cancelled son durumlardır. İki saat sonra yalnızca bekleme biter, görev iptal olmaz.

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

05Sonuçları indir

output_files içindeki s3_key değerini URL kodlayıp fileId olarak kullanın. proxy=true özgün dosyayı aynı kaynaktan sahiplik denetimiyle aktarır.

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

/api/v1/tasks/{taskId}/download adresine Bearer isteği asıl dosyayı veya ZIP’i doğrudan döndürür. Saklama süresi geçerlidir; API anahtarı nesne depolamaya iletilmez.

Hatalar ve kurtarma

HTTP durumunu ve özgün error.code, message, details değerlerini okuyun. Yalnızca metne dayanmayın veya hatayı sonuç dosyası olarak kaydetmeyin.

400	Dosya, parametre ve JSON’u denetleyin.
401	Anahtar eksik, geçersiz, süresi dolmuş veya iptal edilmiş.
402	Yetersiz kredi; bakiyeyi denetleyin.
403	Salt okunur veya erişim izni yok.
404	Kaynak yok ya da başka hesaba ait.
409	Fiyat veya durum değişti; hata kodunu okuyun.
413	Dosya araç sınırını aşıyor.
429	Çok fazla istek; Retry-After bekleyin.
503	Bakım veya geçici arıza; hatayı saklayıp sonra sorgulayın.

429 için Retry-After bekleyin; yoksa sınırlı artan bekleme kullanın. Yalnızca güvenli okumaları yineleyin. Yükleme veya görev POST zaman aşımında yeniden oluşturmadan önce ilk sonucu denetleyin.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Bu API anahtarı işleme izin vermiyor.",
    "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.json içindeki task_id ile sorgulamadan devam edin. Yakın gönderimleri görev listesinde denetleyin; yalnızca durdurmak için cancel çağırın.

API başvurusu

Yollar aynı sitenin /api/v1 önekini kullanır. Anahtarlar yalnızca kendi kaynaklarına erişir; hesap, anahtar oluşturma, yönetim veya dahili callback erişimi yoktur.

GET	`/api/v1/tools`	Araç kataloğu
GET	`/api/v1/tools/{toolId}`	Parametre ve giriş sınırları
GET	`/api/v1/credits/balance`	Kredi bakiyesi
POST	`/api/v1/tools/{toolId}/quote`	Güncel fiyat
POST	`/api/v1/tools/{toolId}/upload`	Dosya yükle
POST	`/api/v1/tools/{toolId}/tasks`	Fiyatı onayla ve gönder
GET	`/api/v1/tasks/{taskId}`	İlerlemeyi sorgula
GET	`/api/v1/tasks`	Görevleriniz
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Sonuçları indir
POST	`/api/v1/tasks/{taskId}/cancel`	Kendi görevini iptal et

midi-converter ve midi-lyrics tarayıcıda çalışır; sunucu yükleme veya yürütme API’si yoktur. Diğer araçların ayrıntıları durum, biçim, boyut ve parametreleri belirler.

Araç kataloğu