Integration guide · API

Updated 2026-10-22

Call existing tools over HTTPS with a personal API key. These sequential examples separate vocals from an MP3. Read the target tool parameters and input limits before changing tools.

Requires Bash, curl 7.76+ and jq. Run all steps in the same terminal.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Setup and authentication

Create a Read and execute key in your account. Send Authorization: Bearer from the command line; no login cookies, CSRF headers or browser session refresh is needed.

Empty tool and IP lists allow all; account policies still apply. Budgets use UTC days/months. Interrupted transfers retain their authorized allocation. The new key inherits permissions and the original expiry. Update scripts within the old key’s remaining five-minute grace period.

Create key →

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 a file

Request a signed upload URL, then PUT the original file. Use the actual byte count and the same Content-Type in both requests.

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

Signed upload URLs normally last 15 minutes. Do not send the API key to PUT uploads. Examples use single PUT; when opting into multipart_supported=true, upload returned parts and call upload/multipart/complete, or abort on failure.

03Confirm price and submit

Read the selected tool/model base price and send the response unchanged as pricing. Save task_id after submission. Quantity and preprocessing options still follow tool pricing rules; RVC training first needs analysis and a training quote.

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)

A quote does not reserve credits. On 409 PRICE_CHANGED, read and confirm the new price before submitting again. Music generation and reference cover require parameters for the selected models.

Keep request-key.txt and request.json. The same account, Idempotency-Key and identical payload replay the original task. Use a new key for a new task; reconcile an unresolved submission before rerunning.

04Poll task progress

Poll every 3 seconds. Download only after completed; failed, timeout and cancelled are terminal states. Examples stop waiting after two hours without cancelling the task.

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

05Download results

URL-encode the s3_key from output_files and use it as fileId. proxy=true streams the original file through the same-origin API with task ownership checks.

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 requests to /api/v1/tasks/{taskId}/download return original bytes or a ZIP directly. File retention applies; the API key is never forwarded to object storage.

Errors and recovery

Inspect the HTTP status and raw error.code, message and details. Do not depend only on message text or save an error response as an output file.

400	Check the file, parameters and JSON structure.
401	Key missing, invalid, expired or revoked.
402	Insufficient credits; check your balance.
403	Read-only permission or no access to this resource.
404	Tool, task or file missing, or owned by another account.
409	Price or task state changed; inspect the error code.
413	File exceeds the tool size limit.
429	Too many requests; wait for Retry-After.
503	Maintenance or a temporary dependency failure; retain the error and check later.

On 429 wait for Retry-After, or use bounded backoff if absent. Retry only safe reads such as status and downloads. If an upload allocation or task POST times out, check the original result before creating anything again.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "This API key cannot perform this operation.",
    "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

Keep task_id in task.json and resume from polling. Check recent submissions in the task list; call cancel only when you intend to stop that task.

API reference

All paths use /api/v1 on the same site. Keys access only your business resources, not account management, key creation, admin or internal callbacks.

GET	`/api/v1/tools`	Tool catalog
GET	`/api/v1/tools/{toolId}`	Parameters and input limits
GET	`/api/v1/credits/balance`	Credit balance
POST	`/api/v1/tools/{toolId}/quote`	Current price
POST	`/api/v1/tools/{toolId}/upload`	Upload a file
POST	`/api/v1/tools/{toolId}/tasks`	Confirm price and submit
GET	`/api/v1/tasks/{taskId}`	Poll task progress
GET	`/api/v1/tasks`	Your task list
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Download results
POST	`/api/v1/tasks/{taskId}/cancel`	Cancel your task

midi-converter and midi-lyrics run locally in the browser without server upload or execution APIs. For other tools, the detail endpoint defines availability, formats, size limits and parameters.

Tool catalog