핵심
API Reference
엔드포인트, 인증, 응답 헤더 및 오류
개요
TokenLab은 OpenAI 호환 엔드포인트와 Anthropic 및 Gemini 요청 형식을 지원합니다. 기존 OpenAI 클라이언트는 /v1을 사용할 수 있으며, 애플리케이션이 해당 API에 특화된 동작을 필요로 하는 경우에만 다른 형식을 선택하십시오. POST /v1/responses는 선택 사항이며 모델 지원 여부에 따라 달라집니다.
Base URL
https://api.tokenlab.sh인증
모델 요청에는 TokenLab API 키가 사용됩니다. 표준 인증 헤더는 다음과 같습니다:
Authorization: Bearer sk-your-api-keyGET /v1/models, GET /v1/models/{model}, GET /v1/models/{model}/pricing 및 GET /v1/pricing은 공개되어 있으며 키가 필요하지 않습니다. Anthropic Messages는 x-api-key도 허용하며, Gemini는 Bearer 인증뿐만 아니라 x-goog-api-key 또는 ?key=도 허용합니다. /v1/management/*는 관리 토큰(mt-...)이 필요합니다.
콘솔에서 API 키를 발급받으십시오.
전달 정책 (Delivery policy)
생성 요청은 X-TokenLab-Delivery-Policy: auto | verified | official을 허용합니다. 요청 헤더는 API 키 설정을 재정의하며, 이는 다시 워크스페이스 기본값을 재정의합니다.
Auto는 사용 가능한 경우 TokenLab Verified를 사용하고, 필요시 Official을 사용합니다. 요청을 완료하는 옵션에 대해 비용이 청구됩니다.TokenLab Verified는 TokenLab에 의해 전달이 검증됩니다. Verified 가격이 적용됩니다.Official은 모델 제작자가 게시한 가격인 Official 가격으로 청구됩니다.- 실시간 세션은 API 키 또는 워크스페이스 설정을 사용하며 요청 재정의를 허용하지 않습니다.
잘못된 헤더는 400을 반환합니다. 요청한 옵션을 사용할 수 없는 경우, TokenLab은 503 delivery_tier_unavailable과 요청 ID를 반환합니다. retryable을 확인하십시오. 선택한 작업의 공급이 없을 경우 false가 됩니다. 동일한 요청을 변경 없이 반복하지 마십시오.
요청 폼이 있는 API 페이지는 귀하의 TokenLab API 키를 허용하며 실제 요청을 보냅니다. 이러한 요청은 귀하의 계정 잔액과 한도를 사용합니다. cURL, Postman 또는 SDK를 사용할 수도 있습니다.
지원되는 엔드포인트
채팅 및 텍스트 생성
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/chat/completions | POST | OpenAI 호환 채팅 완성 |
/v1/messages | POST | Anthropic 호환 메시지 |
/v1/messages/count_tokens | POST | 메시지 요청의 입력 토큰 수 계산 |
/v1/messages/batches | POST, GET | 메시지 배치 생성 및 목록 조회 |
/v1/messages/batches/{message_batch_id} | GET, DELETE | 메시지 배치 검색 또는 삭제 |
/v1/messages/batches/{message_batch_id}/results | GET | 결과 읽기 |
/v1/messages/batches/{message_batch_id}/cancel | POST | 메시지 배치 취소 |
/v1/responses | POST | OpenAI Responses API |
/v1/responses/{id} | GET, DELETE | 저장된 응답 검색 또는 삭제 |
/v1/responses/compact | POST | Responses 대화 컨텍스트 압축 |
/v1/translations | POST | 텍스트 간 번역 |
임베딩 및 리랭크 (Embeddings & Rerank)
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/embeddings | POST | 텍스트 임베딩 생성 |
/v1/multimodal/embeddings | POST | 멀티모달 임베딩 모델로 임베딩 생성 |
/v1/rerank | POST | 문서 리랭크 |
결정 (Decisions)
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/systemone | POST | 유형화된 결정 질문 평가 |
파일 및 배치
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/files | POST, GET | 파일 업로드 및 목록 조회 |
/v1/files/{file_id} | GET, DELETE | 파일 검색 또는 삭제 |
/v1/files/{file_id}/content | GET | 파일 콘텐츠 다운로드 |
/v1/batches | POST, GET | 배치 생성 및 목록 조회 |
/v1/batches/{batch_id} | GET | 배치 검색 |
/v1/batches/{batch_id}/cancel | POST | 배치 취소 |
이미지
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/images/generations | POST | 텍스트로부터 이미지 생성 |
/v1/images/edits | POST | 이미지 편집 |
/v1/images/variations | POST | 이미지 변형 생성 |
/v1/images/generations/{id} | GET | 작업 기반 이미지 응답을 위한 호환성 상태 경로 |
이미지 모델은 완성된 이미지 또는 비동기 작업을 반환할 수 있습니다. 응답에 status: "pending" 또는 작업 ID가 포함된 경우 GET /v1/tasks/{id}를 폴링하십시오.
오디오
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/audio/speech | POST | 텍스트 음성 변환 (TTS) |
/v1/audio/transcriptions | POST | 음성 텍스트 변환 (STT) |
/v1/audio/translations | POST | 음성을 영어 텍스트로 번역 |
실시간 (Realtime)
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/realtime?model={model} | WS | 실시간 WebSocket 세션 |
WebSocket 업그레이드에는 /v1/realtime을 사용하십시오. 일반 GET /v1/realtime은 엔드포인트 메타데이터를 반환합니다. 이는 OpenAI Realtime REST 인터페이스가 아니며, client-secret, Calls 및 레거시 베타 세션 엔드포인트는 사용할 수 없습니다.
비디오
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/videos/generations | POST | 비디오 생성 작업 생성 |
/v1/videos/generations/{id} | GET | 호환성 상태 경로 |
/v1/videos/assets | POST, GET | Seedance 자료 에셋 생성 및 목록 조회 |
/api/v3/contents/generations/tasks | POST, GET | Volcengine 요청 형식을 사용하는 Seedance 작업 |
작업 id를 사용하여 GET /v1/tasks/{id}를 폴링하십시오. /v1/videos/generations/{id}는 기존 통합을 위해 계속 사용할 수 있습니다.
비동기 작업 (Async Tasks)
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/tasks/{id} | GET | 모든 비동기 작업의 상태 |
/v1/tasks/{id} | DELETE | 비동기 작업 취소 |
이미지, 비디오, 음악, 3D, Worlds 및 비동기 오디오 전사와 같은 모든 비동기 작업에 대해 GET /v1/tasks/{id}를 폴링하십시오. 생성 응답의 id 또는 task_id를 사용하십시오. Worlds 생성 응답은 /v1/worlds/generations/{id} 하위에 poll_url을 반환하며, 해당 경로로 /v1/tasks/{id}를 폴링하십시오. 이 페이지의 모달리티별 상태 경로는 기존 통합을 위한 호환성 엔드포인트입니다.
음악
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/music/generations | POST | 음악 생성 작업 생성 |
/v1/music/generations/{id} | GET | 호환성 상태 경로 |
3D 생성
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/3d/generations | POST | 3D 모델 생성 작업 생성 |
/v1/3d/generations/{id} | GET | 호환성 상태 경로 |
Worlds
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/worlds/generations | POST | 월드 생성 작업 생성 |
/v1/worlds/list | POST | 월드 목록 조회 |
/v1/worlds/{id} | GET, DELETE | 월드 검색 또는 삭제 |
/v1/worlds/media-assets/prepare-upload | POST | 미디어 에셋 업로드 준비 |
모델 및 가격
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1/models | GET | 사용 가능한 모든 모델 목록 조회 |
/v1/models/{model} | GET | 특정 모델 정보 조회 |
/v1/models/{model}/pricing | GET | 단일 모델 가격 조회 |
/v1/pricing | GET | 모델 가격 목록 조회 |
Gemini (v1beta)
네이티브 Google Gemini API 형식 지원:
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/v1beta/models | GET | Gemini 요청을 수락하는 모델 목록 조회 |
/v1beta/models/{model} | GET | 모델 조회 |
/v1beta/models/{model}:generateContent | POST | 콘텐츠 생성 |
/v1beta/models/{model}:streamGenerateContent | POST | 스트림 콘텐츠 생성 |
/v1beta/models/{model}:countTokens | POST | 토큰 수 계산 |
/v1beta/files, /v1beta/cachedContents | POST, GET, DELETE | Gemini 파일 및 캐시된 콘텐츠 |
Gemini 엔드포인트는 표준 Bearer 토큰 외에도 ?key= 쿼리 매개변수 인증을 지원합니다.
관리 (Management)
/v1/management/*는 관리 토큰을 사용하여 잔액, API 키 및 웹훅을 관리합니다. 관리 API를 참조하십시오.
응답 형식
각 엔드포인트는 고유한 API 형식을 유지합니다. 아래의 성공 및 오류 예시는 Chat Completions 형식을 사용합니다.
성공 응답
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1234567890,
"model": "gpt-5.6-terra",
"choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}응답 헤더
헤더가 제공되는 경우 이를 사용하십시오.
| 헤더 | 설명 |
|---|---|
X-Request-ID | 지원 및 디버깅을 위한 요청 식별자 |
X-Routing-Time-MS | 비스트리밍: 업스트림 응답이 도착할 때까지의 총 소요 시간(밀리초, 업스트림 큐잉과 추론 포함). 스트리밍: 항상 0. 라우팅이나 큐잉 측정값이 아닙니다. |
X-Task-ID | 작업 기반 응답을 위한 공개 비동기 작업 식별자 |
X-Billing-Transaction-ID | 최종 청구 후의 청구 트랜잭션 식별자 |
공식적인 요청 거부에는 서비스가 보고한 오류와 공개 서비스 이름이 포함된 upstream이 포함될 수 있습니다. API 오류 처리를 참조하십시오.
오류 응답
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}속도 제한 (Rate Limits)
제한은 계정 등급에 따라 다르며 API 키별로 적용됩니다. 429 응답에는 Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining 및 X-RateLimit-Reset이 포함됩니다. 등급 및 재시도 방법은 속도 제한을 참조하십시오.
OpenAPI 사양
OpenAPI 사양
전체 OpenAPI 3.1 사양 다운로드