Руководство по интеграции · API

Руководство по интеграции · API · TelkNet

Вызывайте инструменты по 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 загрузки и выполнения на сервере. Для других инструментов статус, форматы, размер и параметры указаны в деталях.

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

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,