Посібник з інтеграції · API

Оновлено 2026-10-22

Викликайте інструменти через HTTPS з особистим ключем. Послідовні приклади відокремлюють вокал з MP3. Перед зміною інструмента перевірте параметри й обмеження.

Потрібні Bash, curl 7.76+ і jq. Виконуйте в одному терміналі.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Підготовка й автентифікація

Створіть ключ Читання та виконання і надішліть Authorization: Bearer. Cookie, CSRF і оновлення сесії браузера не потрібні.

Порожні списки дозволяють усі інструменти та IP; політика облікового запису залишається чинною. Ліміти за UTC. Перервана передача зберігає виділений обсяг. Новий ключ успадковує права й початковий строк дії. Оновіть скрипти протягом перехідного періоду до п’яти хвилин.

Створити ключ →

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"

02Завантажити файл

Отримайте підписаний URL і надішліть оригінал через PUT. Вкажіть реальний розмір у байтах та однаковий 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 зазвичай діє 15 хвилин. Не надсилайте ключ до PUT. Приклад використовує один PUT; з multipart_supported=true надішліть parts і викличте upload/multipart/complete, при збої — abort.

03Підтвердити ціну й надіслати

Отримайте базову ціну інструмента/моделі, передайте без змін у pricing і збережіть task_id. Кількість і попередня обробка оплачуються за правилами інструмента; для RVC спершу потрібні аналіз і розрахунок навчання.

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)

Розрахунок ціни не резервує кредити. При 409 PRICE_CHANGED отримайте й підтвердьте нову ціну. Генерація музики й кавер потребують параметрів вибраних моделей.

Збережіть request-key.txt і request.json. Той самий обліковий запис, Idempotency-Key та ідентичний вміст повертають початкове завдання. Для нового завдання потрібен новий ключ; спочатку перевірте надсилання з невідомим результатом.

04Перевірити перебіг

Перевіряйте кожні 3 секунди. Отримуйте файл після completed; failed, timeout, cancelled — кінцеві стани. Через дві години завершується очікування, не завдання.

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

05Отримати результати

Закодуйте s3_key з output_files для URL і використайте як fileId. proxy=true передає оригінал із того ж джерела з перевіркою власника.

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-запит до /api/v1/tasks/{taskId}/download одразу повертає оригінал або ZIP. Діють строки зберігання; ключ API не передається до сховища об’єктів.

Помилки й відновлення

Перевірте HTTP-статус та початкові error.code, message, details. Не покладайтеся лише на текст і не зберігайте помилку як результат.

400	Перевірте файл, параметри й JSON.
401	Ключ відсутній, недійсний, прострочений або відкликаний.
402	Недостатньо кредитів; перевірте баланс.
403	Лише читання або немає доступу.
404	Ресурсу немає або він належить іншому акаунту.
409	Змінилася ціна чи стан; прочитайте код.
413	Файл перевищує ліміт інструмента.
429	Забагато запитів; дочекайтеся Retry-After.
503	Обслуговування чи тимчасовий збій; збережіть помилку й перевірте пізніше.

При 429 дочекайтеся Retry-After або застосуйте обмежену затримку. Повторюйте лише безпечне читання. Після тайм-ауту POST перевірте початковий результат, не створюйте завдання повторно.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Цей ключ API не дозволяє операцію.",
    "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_id у task.json і продовжте опитування. Перевіряйте недавні надсилання у списку; cancel викликайте лише для зупинки.

Довідник API

Шляхи використовують /api/v1 того ж сайту. Ключі надають доступ лише до власних ресурсів, без керування акаунтом, створення ключів, адмінки та внутрішніх callback.

GET	`/api/v1/tools`	Каталог інструментів
GET	`/api/v1/tools/{toolId}`	Параметри й обмеження
GET	`/api/v1/credits/balance`	Баланс кредитів
POST	`/api/v1/tools/{toolId}/quote`	Поточна ціна
POST	`/api/v1/tools/{toolId}/upload`	Завантажити файл
POST	`/api/v1/tools/{toolId}/tasks`	Підтвердити ціну й надіслати
GET	`/api/v1/tasks/{taskId}`	Перевірити перебіг
GET	`/api/v1/tasks`	Ваші завдання
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Отримати результати
POST	`/api/v1/tasks/{taskId}/cancel`	Скасувати власне завдання

midi-converter і midi-lyrics працюють у браузері без API завантаження й виконання на сервері. Для інших інструментів статус, формати, розмір і параметри наведено в деталях.

Каталог інструментів