TokenLab

텍스트

메시지 생성 (Create Message)

Anthropic Messages API 형식을 사용하여 메시지를 생성합니다

POST
/v1/messages

개요

이 엔드포인트는 네이티브 Anthropic Messages 형식을 허용하므로, Anthropic SDK 및 이를 기반으로 구축된 도구들이 TokenLab 기본 URL과 호환됩니다. accepted_request_formats에 anthropic_messages가 나열된 모델(Claude 모델 및 기타 일부 모델)에서 작동합니다.

messages는 user 및 assistant 턴을 포함합니다. 시스템 지침은 최상위 system 필드에 넣으십시오. max_tokens는 필수입니다. system 또는 tool과 같은 역할을 사용하는 OpenAI 스타일 메시지의 경우 채팅 완성(Chat Completions)을 사용하십시오.

Anthropic SDK용 기본 URL: https://api.tokenlab.sh (/v1 접미사 없음)

요청 헤더

x-api-keystringheader

귀하의 TokenLab API 키입니다. x-api-key 또는 Authorization: Bearer <API_KEY> 중 하나를 전송하십시오. 두 값을 모두 다른 값으로 전송할 경우, TokenLab은 x-api-key를 사용합니다.

anthropic-versionstringheader

Anthropic API 버전입니다. Anthropic SDK가 자동으로 전송합니다. API를 직접 호출할 때는 2023-06-01을 사용하십시오.

anthropic-betastringheader

쉼표로 구분된 Anthropic 베타 기능 이름입니다. TokenLab은 이 헤더를 그대로 전달하며, 베타 기능의 작동 여부는 모델에 따라 다릅니다. file_id를 참조하는 콘텐츠에는 files-api-2025-04-14가 필요합니다.

요청 본문

지원되는 선택적 매개변수, 허용되는 값 및 기본값은 선택한 모델에 따라 다릅니다. 샘플링, 추론 또는 도구 옵션을 설정하기 전에 해당 모델의 모델 세부 정보를 확인하십시오.

modelstring필수

anthropic_messages 형식을 지원하는 모델의 ID입니다. 현재 기능은 해당 모델의 모델 세부 정보에서 확인하십시오.

messagesarray필수

role(user 또는 assistant)과 content를 포함하는 메시지 객체 배열입니다. 최대 100,000개의 메시지까지 가능합니다.

content는 일반 문자열이거나 콘텐츠 블록의 배열일 수 있습니다. 이미지를 전송하려면 이미지 URL이나 Base64 문자열을 일반 텍스트에 직접 넣는 대신 구조화된 콘텐츠 블록을 사용하십시오. tool_use, tool_result, thinking, document와 같은 기타 네이티브 블록은 이를 지원하는 모델에서 허용됩니다.

콘텐츠 블록 예시:

  • 텍스트 블록: { "type": "text", "text": "이 이미지를 설명해 주세요" }
  • URL을 통한 이미지 블록: { "type": "image", "source": { "type": "url", "url": "https://example.com/image.jpg" } }
  • Base64를 통한 이미지 블록: { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgoAAA..." } }
max_tokensinteger필수

생성할 최대 토큰 수입니다. 필수 항목이며, TokenLab은 기본값을 추가하지 않습니다. 사용 가능한 최대값은 모델에 따라 다르며, 해당 모델의 모델 세부 정보에서 max_output_tokens를 참조하십시오. 큰 값을 설정하면 요청이 실행되는 동안 TokenLab이 귀하의 잔액에서 보류하는 금액이 증가하며, 보류 금액을 충당할 수 없는 잔액일 경우 402 오류가 반환됩니다.

systemstring | array

messages 배열과 별도로 문자열 또는 텍스트 콘텐츠 블록 배열로 구성된 시스템 프롬프트입니다.

temperaturenumber

샘플링 온도입니다. 지원 여부, 허용 값 및 기본값은 선택한 모델에 따라 다릅니다. 기본값을 사용하려면 이 필드를 생략하십시오.

streamboolean기본값: false

응답을 서버 전송 이벤트(SSE) 스트림으로 반환합니다. 스트리밍을 참조하십시오.

thinkingobject

네이티브 사고(thinking) 구성입니다(예: {"type":"enabled","budget_tokens":10000}). 지원되는 모드, 예산 및 다른 매개변수와의 조합은 선택한 모델에 따라 다릅니다. 수동 예산을 거부하는 것으로 알려진 모델의 경우, TokenLab은 {"type":"enabled"}를 적응형 사고로 실행하고 budget_tokens는 무시합니다.

toolsarray

모델에서 사용할 수 있는 도구입니다. 지원 여부는 선택한 모델에 따라 다릅니다.

tool_choiceobject

네이티브 도구 선택 객체입니다(예: {"type":"auto"}). 지원되는 유형은 선택한 모델에 따라 다릅니다.

cache_controlobject

프롬프트 캐싱 마커입니다(예: {"type":"ephemeral"}). 1시간 캐시를 위해 "ttl": "1h"를 추가하십시오. 최상위 수준에서 설정하면 자동 캐싱이 켜집니다. system 블록, tools 및 콘텐츠 블록에서도 설정할 수 있습니다. 지원 여부는 모델에 따라 다르며, 지원하는 모델은 capabilities에 prompt-cache를 나열합니다.

top_pnumber

뉴클리어스 샘플링 매개변수입니다. temperature 또는 top_p 중 하나만 사용하십시오. 지원 여부는 선택한 모델에 따라 다릅니다.

top_kinteger

각 토큰에 대해 상위 K개 옵션에서만 샘플링합니다. 지원 여부는 선택한 모델에 따라 다릅니다.

stop_sequencesarray

모델의 생성을 중단시키는 사용자 지정 중단 시퀀스입니다. 최대 8,191개까지 가능합니다.

metadataobject

Anthropic 형식의 요청 메타데이터입니다. user_id는 최종 사용자를 위한 불투명 식별자입니다.

service_tierstring

auto 및 standard_only만 적용됩니다. TokenLab은 표준 티어에 대해서만 가격을 책정하며 다른 값은 무시합니다.

응답

idstring

고유 메시지 식별자입니다.

typestring

항상 message입니다.

rolestring

항상 assistant입니다.

contentarray

text, thinking 또는 tool_use와 같은 콘텐츠 블록 배열입니다.

modelstring

응답을 생성한 모델입니다.

stop_reasonstring

end_turn, max_tokens, stop_sequence 또는 tool_use와 같이 생성이 중단된 이유입니다. 모델은 refusal과 같은 다른 값을 반환할 수도 있습니다.

stop_sequencestring | null

생성을 종료한 중단 시퀀스이거나 null입니다.

usageobject

input_tokens 및 output_tokens를 포함한 토큰 사용량입니다. 모델이 프롬프트 캐시 토큰을 보고할 때, usage에는 cache_creation_input_tokens 및 cache_read_input_tokens도 포함됩니다.

모든 응답은 request-id 및 X-Request-ID 헤더에 요청 ID를 포함합니다. 지원팀에 문의할 때 이 ID를 인용하십시오.

요청

curl -X POST "https://api.tokenlab.sh/v1/messages" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

응답

Response
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-sonnet-5",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 15,
    "output_tokens": 10
  }
}

비전 입력 예시

비전을 지원하는 Claude 모델의 경우, 이미지를 messages[].content 내부에 구조화된 이미지 블록으로 배치하십시오.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "이 이미지를 설명해 주세요."
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/demo.jpg"
          }
        }
      ]
    }
  ]
}
{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "이 이미지를 설명해 주세요."
        },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ..."
          }
        }
      ]
    }
  ]
}

확장된 사고(Extended Thinking) 예시

reasoning 기능이 있는 모델을 사용하십시오. max_tokens와 budget_tokens를 모델의 한계치에 맞게 조정하십시오. 일부 모델은 다른 사고 구성을 필요로 합니다.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={
        "type": "enabled",
        "budget_tokens": 10000
    },
    messages=[{"role": "user", "content": "이 수학 문제를 풀어보세요..."}]
)

for block in message.content:
    if block.type == "thinking":
        print(f"Thinking: {block.thinking}")
    elif block.type == "text":
        print(f"Response: {block.text}")

스트리밍

"stream": true를 설정하여 Anthropic 서버 전송 이벤트(message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop)를 수신하십시오. 토큰 사용량은 message_start 및 message_delta에서 전달됩니다.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh"
)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "이야기를 하나 들려주세요"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
  • 모델이 작동하는 동안 스트림은 : keep-alive와 같은 SSE 주석 라인을 포함할 수 있습니다. SDK는 이를 무시합니다.
  • 오류가 발생해도 HTTP 상태는 200일 수 있습니다. 스트림이 시작된 후 오류가 발생하면 아래와 동일한 오류 본문을 포함한 event: error 이벤트로 전달됩니다.

오류

오류는 Anthropic 오류 형식을 사용합니다. request_id는 TokenLab 요청 ID입니다. 일부 오류에는 code 및 hint와 같은 필드가 추가됩니다.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens: 필수 항목입니다. /v1/messages는 네이티브 Anthropic 계약을 따르며 기본 max_tokens 값을 추론하지 않습니다."
  },
  "request_id": "req_01JEXAMPLE"
}
상태error.type일반적인 원인
400invalid_request_error누락되거나 잘못된 필드, 알 수 없는 모델, 또는 Messages 형식을 허용하지 않는 모델
401authentication_errorAPI 키가 누락되었거나 유효하지 않음
402billing_error잔액이 요청을 충당할 수 없음(error.code는 insufficient_balance). 지출 한도에 도달한 API 키도 402를 반환하며, error.code는 quota_exceeded, error.type은 rate_limit_error임
403permission_errorAPI 키가 요청된 모델을 사용할 수 없거나, 계정이 정지 또는 제한됨
409conflict_error동일한 Idempotency-Key로 재시도함. 멱등성 키를 사용한 안전한 재시도 참조
413request_too_large요청 입력이 너무 큼
429rate_limit_error너무 많은 요청
500, 502, 503api_error 또는 overloaded_error요청을 완료할 수 없거나 현재 사용할 수 있는 경로가 없음. 나중에 재시도하십시오
504timeout_error요청 시간이 초과됨

관련 인터페이스

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

동일한 요청이 두 번 실행되지 않도록 방지하는 선택적 키입니다. 각 요청마다 UUID와 같은 새로운 고유 값을 전송하고, 타임아웃 후 재시도 시에도 동일한 값을 유지하십시오. 동일한 키를 사용한 재시도는 다시 실행되지 않으며, idempotency_replay_unavailable와 함께 409를 반환하거나, 본문이 변경된 경우 일반적으로 idempotency_conflict를 반환합니다. 예외: 스트리밍되지 않는 결과가 클라이언트 연결 해제 후 완료된 경우, 24시간 이내에 동일한 키와 본문으로 재시도하면 Idempotent-Replayed: true 헤더와 함께 해당 결과(최대 1MB)를 반환하며 추가 비용은 청구되지 않습니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성 보호를 받지 못합니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.

길이1 <= length <= 255

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json