Integrationsvejledning · API

Integrationsvejledning · API · TelkNet

Kald værktøjer via HTTPS med en personlig API-nøgle. Kør eksemplerne i rækkefølge for at adskille vokal fra MP3. Kontrollér parametre og grænser før skift af værktøj.

Kræver Bash, curl 7.76+ og jq. Kør i samme terminal.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Opsætning og godkendelse

Opret en nøgle med Læsning og udførelse og send Authorization: Bearer. Ingen login-Cookie, CSRF eller fornyelse af browsersession kræves.

Tomme værktøjs- og IP-lister tillader alle; kontoregler gælder stadig. Budgetter følger UTC. Afbrudte overførsler beholder deres tildeling. Den nye nøgle bevarer rettigheder og udløbsdato. Opdatér scripts inden for den højst fem minutter lange overgang.

Opret nøgle →

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"

02Upload fil

Hent en signeret URL og send originalfilen med PUT. Brug det reelle byteantal og samme 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 er normalt gyldig i 15 minutter. Send ikke API-nøglen til PUT. Eksemplet bruger enkelt PUT; ved multipart_supported=true uploades parts og upload/multipart/complete kaldes, eller abort ved fejl.

03Bekræft pris og indsend

Hent basisprisen for valgt værktøj/model, send uændret som pricing og gem task_id. Antal og forbehandling følger værktøjets priser; RVC-træning kræver først analyse og træningstilbud.

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)

Tilbud reserverer ikke kredit. Ved 409 PRICE_CHANGED skal den nye pris hentes og bekræftes. Musikgenerering og referencecover kræver de valgte modellers parametre.

Gem request-key.txt og request.json. Samme konto, Idempotency-Key og identisk indhold returnerer den oprindelige opgave. Brug en ny nøgle til en ny opgave, og afklar usikre indsendelser først.

04Hent opgavestatus

Hent status hvert 3. sekund. Download efter completed; failed, timeout og cancelled er sluttilstande. Efter to timer stoppes ventetiden, ikke opgaven.

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

05Hent resultater

URL-kod s3_key fra output_files og brug den som fileId. proxy=true sender originalen fra samme origin med ejerskabskontrol.

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-anmodninger til /api/v1/tasks/{taskId}/download returnerer originalfilen eller ZIP direkte. Opbevaringsfrister gælder; API-nøglen sendes aldrig til objektlageret.

Fejl og genoptagelse

Læs HTTP-status og oprindelige error.code, message og details. Stol ikke kun på teksten, og gem ikke fejl som resultatfiler.

400	Tjek fil, parametre og JSON.
401	Nøgle mangler, er ugyldig, udløbet eller tilbagekaldt.
402	Utilstrækkelig kredit; tjek saldo.
403	Kun læsning eller ingen adgang.
404	Ressourcen mangler eller tilhører en anden konto.
409	Pris eller status ændret; læs fejlkoden.
413	Filen overskrider værktøjets grænse.
429	For mange anmodninger; følg Retry-After.
503	Vedligeholdelse eller midlertidig fejl; gem fejlen og tjek senere.

Ved 429 ventes efter Retry-After eller med begrænset stigende ventetid. Gentag kun sikre læsninger. Ved timeout på uploadanmodning eller opgave-POST kontrolleres det oprindelige resultat først.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Denne API-nøgle har ikke tilladelse til handlingen.",
    "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

Gem task_id i task.json og genoptag statuskontrol. Tjek nylige indsendelser i listen; kald kun cancel for at stoppe opgaven.

API-reference

Alle stier bruger /api/v1 på samme side. Nøgler gælder egne ressourcer, ikke kontostyring, nye nøgler, admin eller interne callbacks.

GET	`/api/v1/tools`	Værktøjskatalog
GET	`/api/v1/tools/{toolId}`	Parametre og inputgrænser
GET	`/api/v1/credits/balance`	Kreditsaldo
POST	`/api/v1/tools/{toolId}/quote`	Aktuel pris
POST	`/api/v1/tools/{toolId}/upload`	Upload fil
POST	`/api/v1/tools/{toolId}/tasks`	Bekræft pris og indsend
GET	`/api/v1/tasks/{taskId}`	Hent opgavestatus
GET	`/api/v1/tasks`	Dine opgaver
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Hent resultater
POST	`/api/v1/tasks/{taskId}/cancel`	Annuller egen opgave

midi-converter og midi-lyrics kører lokalt i browseren uden server-API til upload eller udførelse. Andre værktøjers detaljer angiver status, formater, størrelse og parametre.

Værktøjskatalog

music-yourmt3, music-yourmt3-ymt3-plus, music-yourmt3-yptf-single-nops, music-yourmt3-yptf-multi-ps, music-yourmt3-yptf-moe-multi-ps, music-miros, music-vocal-harmony-split, music-dry-vocal, music-vocal-split, music-four-stem, music-six-stem, music-drum-split, music-drum-split-drumsep-mdx23c-6, music-mega-53-stem, music-eight-stem, music-restoration, music-custom-stem, music-piano-transkun, music-piano-transkun-standard, music-piano-transkun-v2-aug, music-piano-aria, music-piano-bytedance-pedal, ai-rvc, zonos2-tts, midi-converter, midi-lyrics,