Integrasjonsveiledning · API

Oppdatert 2026-10-22

Kall verktøy via HTTPS med en personlig API-nøkkel. Kjør eksemplene i rekkefølge for vokalseparasjon fra MP3. Sjekk parametere og begrensninger før du bytter verktøy.

Krever Bash, curl 7.76+ og jq. Kjør i samme terminal.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Oppsett og autentisering

Opprett en nøkkel med Lesing og kjøring og send Authorization: Bearer. Ingen innloggings-Cookie, CSRF eller fornyelse av nettleserøkt trengs.

Tomme verktøy- og IP-lister tillater alle; kontoregler gjelder fortsatt. Budsjetter følger UTC. Avbrutte overføringer beholder tildelingen. Den nye nøkkelen beholder rettigheter og utløpsdato. Oppdater skript innen den maksimale overgangstiden på fem minutter.

Opprett nøkkel →

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"

02Last opp fil

Be om signert URL og PUT originalfilen. Bruk faktisk antall byte 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 varer vanligvis 15 minutter. Ikke send API-nøkkelen til PUT. Eksemplet bruker enkel PUT; med multipart_supported=true lastes parts opp før upload/multipart/complete, eller abort ved feil.

03Bekreft pris og send

Hent grunnprisen for valgt verktøy/modell, send uendret som pricing og lagre task_id. Antall og forbehandling følger verktøyprisene; RVC-trening krever først analyse og treningstilbud.

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)

Pristilbud reserverer ikke kreditter. Ved 409 PRICE_CHANGED må ny pris leses og bekreftes. Musikkgenerering og referansecover krever valgte modellparametere.

Behold request-key.txt og request.json. Samme konto, Idempotency-Key og identisk innhold returnerer den opprinnelige oppgaven. Bruk en ny nøkkel for nye oppgaver, og avklar usikre innsendinger først.

04Sjekk fremdrift

Sjekk hvert 3. sekund. Last ned ved completed; failed, timeout og cancelled er sluttilstander. Etter to timer stopper ventingen, ikke oppgaven.

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

05Last ned resultater

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

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-forespørsler til /api/v1/tasks/{taskId}/download returnerer originalfilen eller ZIP direkte. Lagringsfrister gjelder; API-nøkkelen sendes aldri til objektlageret.

Feil og gjenopptakelse

Les HTTP-status og originale error.code, message, details. Ikke stol bare på teksten, og ikke lagre feil som resultatfiler.

400	Sjekk fil, parametere og JSON.
401	Nøkkel mangler, er ugyldig, utløpt eller tilbakekalt.
402	For få kreditter; sjekk saldoen.
403	Kun lesing eller ingen tilgang.
404	Ressurs mangler eller eies av en annen konto.
409	Pris eller status endret; les feilkoden.
413	Filen er større enn verktøygrensen.
429	For mange forespørsler; følg Retry-After.
503	Vedlikehold eller midlertidig feil; behold feilen og sjekk senere.

Ved 429 følg Retry-After eller begrenset økende venting. Gjenta bare trygge leseoperasjoner. Ved tidsavbrudd på opplastingsforespørsel eller oppgave-POST sjekk først det opprinnelige resultatet.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "API-nøkkelen tillater ikke denne 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

Behold task_id i task.json og gjenoppta fra statuskontroll. Sjekk nylige innsendinger i listen; bruk cancel bare for å stoppe oppgaven.

API-referanse

Alle stier bruker /api/v1 på samme nettsted. Nøkler gjelder egne ressurser, ikke kontoadministrasjon, nye nøkler, admin eller interne callbacks.

GET	`/api/v1/tools`	Verktøykatalog
GET	`/api/v1/tools/{toolId}`	Parametere og grenser
GET	`/api/v1/credits/balance`	Kredittsaldo
POST	`/api/v1/tools/{toolId}/quote`	Gjeldende pris
POST	`/api/v1/tools/{toolId}/upload`	Last opp fil
POST	`/api/v1/tools/{toolId}/tasks`	Bekreft pris og send
GET	`/api/v1/tasks/{taskId}`	Sjekk fremdrift
GET	`/api/v1/tasks`	Dine oppgaver
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Last ned resultater
POST	`/api/v1/tasks/{taskId}/cancel`	Avbryt egen oppgave

midi-converter og midi-lyrics kjører lokalt i nettleseren uten server-API for opplasting eller kjøring. Andre verktøydetaljer angir status, formater, størrelse og parametere.

Verktøykatalog