Guia de integração · API

Atualizado 2026-10-22

Use uma chave pessoal para chamar ferramentas por HTTPS. Execute os exemplos em sequência para separar voz de um MP3. Consulte parâmetros e limites antes de trocar de ferramenta.

Requer Bash, curl 7.76+ e jq. Execute no mesmo terminal.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Configuração e autenticação

Crie uma chave de Leitura e execução e envie Authorization: Bearer. Não precisa de Cookie, CSRF nem renovar sessão do navegador.

Listas vazias permitem todas as ferramentas e IPs; as regras da conta continuam válidas. Limites em UTC. Transferências interrompidas mantêm a alocação. A nova chave mantém permissões e vencimento. Atualize os scripts durante o prazo de transição de no máximo cinco minutos.

Criar chave →

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"

02Enviar arquivo

Solicite uma URL assinada e envie o original com PUT. Use o tamanho real em bytes e o mesmo 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)"

URLs normalmente valem 15 minutos. Não envie a chave ao PUT. O exemplo usa PUT simples; com multipart_supported=true, envie parts e chame upload/multipart/complete, ou abort em caso de falha.

03Confirmar preço e enviar

Leia o preço base da ferramenta/modelo, envie sem alterações em pricing e guarde task_id. Quantidade e pré-processamento seguem as tarifas da ferramenta; RVC exige antes análise e cotação de treinamento.

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 cotação não reserva créditos. Em 409 PRICE_CHANGED, consulte e confirme o novo preço. Geração musical e cover de referência exigem parâmetros dos modelos selecionados.

Guarde request-key.txt e request.json. A mesma conta, Idempotency-Key e conteúdo idêntico retornam a tarefa original. Use uma chave nova para outra tarefa e confira envios de resultado incerto antes de repetir.

04Consultar progresso

Consulte a cada 3 segundos. Baixe após completed; failed, timeout e cancelled são finais. O exemplo para de esperar em duas horas sem cancelar a tarefa.

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

05Baixar resultados

Codifique s3_key de output_files para URL e use como fileId. proxy=true transmite o original pela mesma origem com verificação do proprietário.

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

Requisições Bearer a /api/v1/tasks/{taskId}/download retornam o original ou um ZIP diretamente. Vale o prazo de retenção; a chave API nunca é encaminhada ao armazenamento.

Erros e recuperação

Verifique status HTTP e error.code, message e details originais. Não dependa só da mensagem nem salve erros como arquivos de resultado.

400	Verifique arquivo, parâmetros e JSON.
401	Chave ausente, inválida, expirada ou revogada.
402	Créditos insuficientes; confira o saldo.
403	Somente leitura ou sem acesso.
404	Recurso ausente ou de outra conta.
409	Preço ou estado alterado; leia o código.
413	Arquivo excede o limite da ferramenta.
429	Muitas solicitações; respeite Retry-After.
503	Manutenção ou falha temporária; guarde o erro e consulte depois.

Em 429, aguarde Retry-After ou use espera progressiva limitada. Repita apenas leituras seguras. Se um POST de upload ou tarefa expirar, verifique o resultado original antes de criar outra tarefa.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Esta chave não permite a operação.",
    "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

Guarde task_id em task.json e retome a consulta. Confira envios recentes na lista; chame cancel apenas para interromper a tarefa.

Referência da API

Todos os caminhos usam /api/v1 no mesmo site. Chaves acessam apenas seus recursos, não contas, criação de chaves, administração ou callbacks internos.

GET	`/api/v1/tools`	Catálogo de ferramentas
GET	`/api/v1/tools/{toolId}`	Parâmetros e limites
GET	`/api/v1/credits/balance`	Saldo de créditos
POST	`/api/v1/tools/{toolId}/quote`	Preço atual
POST	`/api/v1/tools/{toolId}/upload`	Enviar arquivo
POST	`/api/v1/tools/{toolId}/tasks`	Confirmar preço e enviar
GET	`/api/v1/tasks/{taskId}`	Consultar progresso
GET	`/api/v1/tasks`	Suas tarefas
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Baixar resultados
POST	`/api/v1/tasks/{taskId}/cancel`	Cancelar sua tarefa

midi-converter e midi-lyrics rodam no navegador sem API de upload ou execução no servidor. Os detalhes das outras ferramentas definem disponibilidade, formatos, tamanho e parâmetros.

Catálogo de ferramentas

<- Documentação

Guia de integração · API

Atualizado 2026-10-22

Use uma chave pessoal para chamar ferramentas por HTTPS. Execute os exemplos em sequência para separar voz de um MP3. Consulte parâmetros e limites antes de trocar de ferramenta.

Requer Bash, curl 7.76+ e jq. Execute no mesmo terminal.

Bash / curl ↓PowerShell 7 ↓Python 3 ↓

01Configuração e autenticação

Crie uma chave de Leitura e execução e envie Authorization: Bearer. Não precisa de Cookie, CSRF nem renovar sessão do navegador.

Criar chave →

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"

02Enviar arquivo

Solicite uma URL assinada e envie o original com PUT. Use o tamanho real em bytes e o mesmo 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)"

URLs normalmente valem 15 minutos. Não envie a chave ao PUT. O exemplo usa PUT simples; com multipart_supported=true, envie parts e chame upload/multipart/complete, ou abort em caso de falha.

03Confirmar preço e enviar

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 cotação não reserva créditos. Em 409 PRICE_CHANGED, consulte e confirme o novo preço. Geração musical e cover de referência exigem parâmetros dos modelos selecionados.

04Consultar progresso

Consulte a cada 3 segundos. Baixe após completed; failed, timeout e cancelled são finais. O exemplo para de esperar em duas horas sem cancelar a tarefa.

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

05Baixar resultados

Codifique s3_key de output_files para URL e use como fileId. proxy=true transmite o original pela mesma origem com verificação do proprietário.

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

Requisições Bearer a /api/v1/tasks/{taskId}/download retornam o original ou um ZIP diretamente. Vale o prazo de retenção; a chave API nunca é encaminhada ao armazenamento.

Erros e recuperação

Verifique status HTTP e error.code, message e details originais. Não dependa só da mensagem nem salve erros como arquivos de resultado.

400	Verifique arquivo, parâmetros e JSON.
401	Chave ausente, inválida, expirada ou revogada.
402	Créditos insuficientes; confira o saldo.
403	Somente leitura ou sem acesso.
404	Recurso ausente ou de outra conta.
409	Preço ou estado alterado; leia o código.
413	Arquivo excede o limite da ferramenta.
429	Muitas solicitações; respeite Retry-After.
503	Manutenção ou falha temporária; guarde o erro e consulte depois.

Em 429, aguarde Retry-After ou use espera progressiva limitada. Repita apenas leituras seguras. Se um POST de upload ou tarefa expirar, verifique o resultado original antes de criar outra tarefa.

JSON

{
  "ok": false,
  "error": {
    "code": "API_KEY_SCOPE",
    "message": "Esta chave não permite a operação.",
    "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

Guarde task_id em task.json e retome a consulta. Confira envios recentes na lista; chame cancel apenas para interromper a tarefa.

Referência da API

Todos os caminhos usam /api/v1 no mesmo site. Chaves acessam apenas seus recursos, não contas, criação de chaves, administração ou callbacks internos.

GET	`/api/v1/tools`	Catálogo de ferramentas
GET	`/api/v1/tools/{toolId}`	Parâmetros e limites
GET	`/api/v1/credits/balance`	Saldo de créditos
POST	`/api/v1/tools/{toolId}/quote`	Preço atual
POST	`/api/v1/tools/{toolId}/upload`	Enviar arquivo
POST	`/api/v1/tools/{toolId}/tasks`	Confirmar preço e enviar
GET	`/api/v1/tasks/{taskId}`	Consultar progresso
GET	`/api/v1/tasks`	Suas tarefas
GET	`/api/v1/tasks/{taskId}/files/{fileId}?proxy=true`	Baixar resultados
POST	`/api/v1/tasks/{taskId}/cancel`	Cancelar sua tarefa

midi-converter e midi-lyrics rodam no navegador sem API de upload ou execução no servidor. Os detalhes das outras ferramentas definem disponibilidade, formatos, tamanho e parâmetros.

Catálogo de ferramentas