핵심 가이드
안정적인 TokenLab 통합 구축하기
비용, 재시도, API 키 및 요청 기록을 효율적으로 관리하세요
우수한 통합은 가격과 모델 선택을 투명하게 공개하고, 일반적인 네트워크 장애 상황에서도 안정적으로 작동하며, 브라우저에 API 키를 절대 노출하지 않습니다. 아래의 관행들은 채팅, 이미지, 비디오, 오디오 및 기타 TokenLab API 전반에 적용됩니다.
최신 데이터를 기반으로 모델 선택하기
모델 이름, 기능 및 가격은 수시로 변경됩니다. 코드나 문서에 고정된 목록을 유지하는 대신 Models API 또는 모델 페이지를 확인하세요.
새로운 사용 사례를 시작할 때:
- 제품에 필요한 기능에 따라 모델을 필터링합니다.
- 현재 TokenLab 가격을 비교합니다.
- 대표적인 사용자 요청을 사용하여 소규모 테스트를 진행합니다.
- 각 요청에 모델 ID를 명시적으로 포함합니다.
모델을 예고 없이 변경하지 마세요. 모델을 교체하면 출력 품질, 가격, 컨텍스트 길이, 사용 가능한 도구 또는 미디어 지원 범위가 달라질 수 있습니다.
비용 상한선 설정하기
텍스트 모델의 경우, 제품에서 실제로 사용할 수 있는 길이로 출력을 제한하세요. 매개변수 이름은 API 및 모델에 따라 다르므로, max_tokens 또는 max_output_tokens를 전송하기 전에 모델 페이지를 확인하세요.
지침이 짧다고 해서 항상 좋은 것은 아니지만, 중복된 컨텍스트와 반복되는 상용구는 항상 입력 토큰을 증가시킵니다. 안정적인 지침은 간결하게 유지하고, 다음 답변에 필요한 기록만 전송하세요.
이미지, 비디오, 음악, 3D 및 Worlds 요청의 경우, 비용은 종종 출력 개수, 재생 시간, 해상도 또는 기타 미디어 옵션에 따라 달라집니다. API가 비용을 제공할 수 있는 경우, 사용자가 비용이 발생하는 생성을 확인하기 전에 현재 예상 비용을 표시하세요.
긴 텍스트 응답 스트리밍하기
스트리밍을 사용하면 답변이 도착하는 대로 표시되므로 사용자가 전체 응답을 기다릴 필요가 없습니다. 이는 토큰 비용을 절감하지는 않습니다.
클라이언트 설정 및 완료 확인을 포함한 전체 예제는 스트리밍을 참조하세요.
연결이 끊기면 답변이 불완전한 것으로 처리하세요. 부분적인 출력을 성공적으로 완료된 것처럼 표시하지 말고, 두 번째 부작용이나 추가 요금이 발생할 수 있는 상황에서 자동으로 요청을 반복하지 마세요.
안전한 경우에만 재시도하기
429 응답은 Retry-After 또는 retry_after 헤더를 확인한 후 재시도하세요. 일시적인 5xx 응답에는 짧은 지수 백오프(exponential backoff)가 적절합니다. 인증, 유효성 검사, 잔액 부족 및 컨텍스트 길이 오류는 애플리케이션이나 사용자의 수정이 필요하므로, 동일한 요청을 다시 보내도 해결되지 않습니다.
Retry-After를 준수하고 중복된 SDK 재시도를 비활성화하는 제한적 재시도 예제는 Rate limits를 참조하세요.
재시도 횟수와 총 시간 제한을 설정하세요. 미디어 생성의 경우 반환된 작업 ID를 저장하세요. Retry safely with an idempotency key에 나열된 요청의 경우 Idempotency-Key를 전송하여, 타임아웃 후 재시도가 동일한 요청을 두 번 실행하거나 과금하지 않도록 하세요.
API 키를 서버에 보관하기
TokenLab API 키를 브라우저 JavaScript, 모바일 애플리케이션 번들, 공개 저장소 또는 클라이언트가 볼 수 있는 로그에 절대 포함하지 마세요.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)개발, 프로덕션 및 독립적인 애플리케이션에는 별도의 API 키를 사용하세요. 각 키에는 필요한 모델과 지출 한도만 부여하세요. 키가 노출되었을 가능성이 있다면 즉시 폐기하세요.
유용한 요청 기록 유지하기
사용자 작업과 사용량 및 지원 기록을 연결할 수 있는 식별자를 저장하세요:
- API 요청에 대한
request_id - 비동기 생성을 위한
task_id - 반환된 경우
billing_transaction_id - 모델 ID 및 엔드포인트
- 자체 사용자, 프로젝트 또는 작업 ID
API 키, 관리 토큰, 전체 비공개 프롬프트, 비공개 미디어 또는 서명된 URL은 기록하지 마세요. Console 및 Management API의 사용량 기록이 청구 금액의 기준이 됩니다. 모델 응답 토큰 수만으로는 최종 청구 금액을 설명하지 못할 수 있습니다.
비동기 작업을 위한 설계
이미지, 비디오, 음악, 3D 및 Worlds API는 결과가 준비되기 전에 응답을 반환할 수 있습니다. 작업 ID를 저장하고 GET /v1/tasks/{id}를 폴링하여 completed 또는 failed 상태가 될 때까지 확인하세요. 상태 조회에서 실패가 나타났다고 해서 생성 자체가 실패했다는 의미는 아닙니다.
취소, 타임아웃 및 중복 요청 처리에 대한 내용은 비동기 작업 및 폴링을 참조하세요.
출시 전 체크리스트
- 배포할 정확한 모델과 API 형식을 사용하여 대표적인 요청을 실행하세요.
- 성공 응답과 일반적인 오류 응답을 모두 확인하세요.
- 제품에 표시된 가격이 현재 TokenLab 가격과 일치하는지 확인하세요.
- 새로 고침, 네트워크 타임아웃 및 반복 클릭 시에도 안전하게 작동하도록 하세요.
- 사용자에게 표시된 결과를 Request ID로 추적할 수 있도록 하세요.