TokenLab

핵심 가이드

로그 및 문제 해결

요청, 작업 및 요금을 추적하는 데 필요한 ID를 보관하세요

로그에 TokenLab 요청, 작업 및 결제 ID를 보관하세요. 이러한 ID는 프롬프트나 개인 미디어를 저장하지 않고도 사용자 작업과 그 결과 및 요금을 연결해 줍니다.

콘솔에서 캡처된 요청 및 응답 세부 정보는 캡처 시점부터 30일 동안 사용할 수 있으며, 물리적 정리 작업이 대기 중이더라도 정확한 만료 시간에 액세스가 종료됩니다. 요청 식별 정보와 결제/사용 내역은 각각 독립적인 수명을 가집니다. 데이터 보존을 참조하세요.

요청에서 조사 및 지원까지

  1. 요청을 소유한 워크스페이스에서 Runs를 엽니다. 해당 요청의 Request ID를 찾아 행을 선택합니다.

  2. 전용 페이지를 보려면 Open full details를 선택하세요. Back to requests를 누르면 목록 필터가 복원됩니다. 링크를 통해 다른 워크스페이스에 액세스할 수는 없으며, 해당 워크스페이스에 권한이 있는 계정을 사용해야 합니다.

  3. 보류 중이거나 알 수 없는 상태인 경우, 먼저 진행 상황을 새로 고침하세요. 실패했거나 응답이 중단된 경우, 가능한 경우 Investigate the issue를 선택하세요. 이는 인앱 Agent에서 해당 요청에 대한 조사를 시작하며, 원래 모델 요청을 다시 실행하지는 않습니다. 성공한 요청은 기본적으로 조사가 필요하지 않습니다.

  4. 여전히 도움이 필요한 경우, 요청 또는 조사 화면에서 고객 지원 요청 작업을 선택하세요. 가능한 경우 연결된 요청 및 대화 내용이 포함된 미리보기가 열립니다. 요약 내용을 검토하고 개인 정보를 제거한 다음, 명시적으로 Submit을 선택하세요. 조사나 미리보기만으로는 지원 요청이 전송되지 않습니다.

  5. 제출 후 확인 내용을 보관하고 Support에서 동일한 대화를 계속하세요. 중복 제출하는 대신 해당 대화창을 사용하여 답변을 받거나 추가 정보를 제공하세요.

보관해야 할 ID

식별자표시 위치용도
request_id오류 본문, 대시보드 로그, 사용 기록요청 수준의 지원 및 조정
id / task_id비동기 생성 및 상태 응답GET /v1/tasks/{id}를 사용한 비동기 작업 폴링
poll_url비동기 생성 응답상태 URL; id를 사용하여 /v1/tasks/{id} 폴링
billing_transaction_id결제 완료된 비스트리밍 응답, 비동기 작업 상태 응답, 사용 기록, X-Billing-Transaction-ID비용 조정
X-Task-ID비동기 작업 응답 헤더헤더 수준의 작업 상관관계 분석
사용자 지정 작업/사용자 ID귀하의 애플리케이션사용자 작업에 대한 TokenLab 요청 찾기

고객 대상 기록에는 TokenLab ID를 사용해야 합니다. 개인 서비스 URL, 캐시 키 또는 진단 메타데이터를 절대 노출하지 마세요.

로그 기록 권장 사항

비밀 정보를 유출하지 않으면서 요청을 진단할 수 있을 만큼만 기록하세요:

  • 엔드포인트, HTTP 메서드, 모델, 상태 코드, 타임스탬프 및 지연 시간.
  • 공개 식별자: request_id, task_id, poll_url 및 존재하는 경우 billing_transaction_id.
  • 요청에 전송된 필드 이름 (전체 프롬프트나 개인 미디어 콘텐츠는 제외).
  • 최종 비동기 상태 응답 및 안전한 오류 필드.
  • 클라이언트 재시도 횟수 및 재시도가 새 작업을 생성했는지 아니면 기존 작업을 재개했는지 여부.

명시적인 보관 권한이 없는 한 Authorization, API 키, 관리 토큰, 서명된 URL, 개인 미디어 URL, 전체 프롬프트 및 사용자 개인 정보는 항상 마스킹(redact) 처리하세요.

문제 해결 매트릭스

증상우선 확인 사항유용한 페이지
401 또는 403API 키, 관리 토큰, 조직 액세스 권한, 키 범위인증
402잔액, API 키 사용 한도결제 및 요금
429계정 등급, 엔드포인트 속도 제한, 재시도 동작속도 제한
400 invalid_request_error지원되지 않는 필드, 잘못된 엔드포인트, 필수 필드 누락 또는 모델 요청 불일치오류 처리
비동기 작업을 찾을 수 없음잘못된 API 키, 잘못 입력된 ID 또는 만료된 작업비동기 작업 및 폴링
비용이 UI와 일치하지 않음결제 시점 차이 또는 잘못된 식별자 비교결제 및 요금

사용량 조정

서버 측 조정을 위해 Management API를 사용하세요:

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video" \
  -H "Authorization: Bearer mt-your-management-token"

GET /v1/management/api-keys/{keyId}/usage는 scene, model, modelVendor, startDate 및 endDate별로 필터링할 수 있습니다. 콘솔 페이지를 스크래핑하거나 응답 토큰 수만으로 요금을 계산하는 대신 이 기록을 사용하세요. 날짜만 포함된 endDate는 해당 날짜의 00:00 UTC를 의미합니다. API 키 사용량 가져오기를 참조하세요.

스트리밍 응답은 스트림이 전송된 후 결제될 수 있으므로, 나중에 사용량이 기록되더라도 결제 헤더가 없을 수 있습니다. 비동기 미디어 작업은 최종 폴링 후에 결제될 수 있습니다.

지원팀에 보낼 정보

지원팀에 문의할 때는 다음 정보를 포함하세요:

  • request_id.
  • 비동기 작업의 경우 task_id 및 poll_url.
  • 존재하는 경우 billing_transaction_id.
  • 엔드포인트, 메서드, 모델, 타임스탬프 및 상태 코드.
  • 요청 필드 이름 및 안전한 오류 본문.
  • 예상 결과 및 사용자가 실제로 확인한 내용.

API 키, 관리 토큰, 개인 미디어, 전체 프롬프트, 개인 서비스 URL 또는 진단 식별자는 포함하지 마세요. 지원팀이 요청 예시를 필요로 하는 경우, 마스킹 처리된 사본을 보내세요.

자동화 권장 사항

  • 반복되는 401, 402, 429 및 5xx 응답에 대해 각각 별도로 알림을 설정하세요. 각 응답은 서로 다른 대응이 필요합니다.
  • 제품 SLA보다 오래 종료되지 않는 비동기 작업을 추적하세요.
  • 동일한 사용자 작업 ID에 대한 중복 생성 시도를 추적하세요.
  • 완료된 작업을 샘플링하여 사용자에게 표시된 자산, 사용 기록 및 저장된 작업 기록이 일치하는지 확인하세요.

API 참조

주제참조
오류 처리오류 처리
속도 제한속도 제한
결제 및 요금결제 및 요금
API 키 사용량 가져오기API 키 사용량 가져오기
작업 상태 가져오기작업 상태 가져오기

이 페이지의 내용