연동 가이드 · API

업데이트됨 2026-10-22

개인 API 키로 HTTPS를 통해 도구를 호출합니다. MP3 보컬 분리 예제를 순서대로 실행하세요. 다른 도구는 먼저 매개변수와 입력 제한을 확인하세요.

Bash, curl 7.76+, jq가 필요합니다. 같은 터미널에서 순서대로 실행하세요.

01준비 및 인증

계정에서 읽기 및 실행 키를 만들고 Authorization: Bearer를 전송하세요. Cookie, CSRF, 브라우저 세션 갱신은 필요 없습니다.

도구와 IP 목록이 비어 있으면 모두 허용하며 계정 정책은 계속 적용됩니다. 한도는 UTC 기준입니다. 전송 중단 시에도 허용량은 사용됩니다. 새 키는 권한과 기존 만료일을 유지합니다. 기존 키의 최대 5분 유예 시간 안에 스크립트를 업데이트하세요.

키 만들기 →

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에 API 키를 보내지 마세요. 예제는 단일 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는 최종 상태입니다. 2시간 후 폴링을 멈춰도 작업은 취소되지 않습니다.

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결과 다운로드

output_files의 s3_key를 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.json의 task_id를 보관하고 폴링부터 재개하세요. 목록에서 최근 제출을 확인하고 중단할 때만 cancel을 호출하세요.

API 참조

같은 사이트의 /api/v1을 사용합니다. 키는 내 업무 리소스만 접근하며 계정 관리, 키 생성, 관리자 및 내부 콜백은 불가합니다.

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를 지원하지 않습니다. 다른 도구의 상태, 형식, 크기와 매개변수는 상세 API에서 확인하세요.

도구 목록