Claude Messages

x-api-key string 필수

BeatAPI 키입니다. Authorization: Bearer <BEATAPI_API_KEY>도 받습니다.

model string 필수

정확한 모델 ID입니다.

허용 값: claude-fable-5-2, claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5

• 계속 동작하는 이전 ID(claude-opus-5, claude-sonnet-5, claude-haiku-4-5-20251001)는 레거시 모델에 있습니다.
• 키로 GET /v1/models를 호출해 사용 가능한 모델을 확인하세요.

max_tokens integer 필수

생성 토큰의 상한이며, 사고 토큰을 포함합니다.

• 항상 보내세요. 없거나 0이면 기본 한도가 적용되며, 이 기본값은 예상보다 낮을 수 있습니다.
• 허용되는 최댓값은 1,073,741,823이며, 그보다 크면 400 bad_request입니다. 위 표에 있는 모델의 최대 출력 이하로 설정하세요.
• max_tokens는 요청에 필요한 잔액을 추정하는 데도 쓰입니다. 실제 출력이 작더라도 값이 너무 크면 402 insufficient_credits로 거부될 수 있습니다. 필요한 만큼만 설정하세요.

messages object[] 필수

대화 내용이며 오래된 메시지부터 나열합니다. 각 메시지에는 role(user 또는 assistant)와 content가 있습니다. content는 문자열이거나 콘텐츠 블록 배열입니다.

• 사용할 블록 유형: text, image(base64 또는 URL 소스), tool_use(어시스턴트 메시지 안), tool_result(사용자 메시지 안).
• messages 배열이 비어 있거나 없으면 400 bad_request입니다.

예시

[
  {
    "role": "user",
    "content": [
      { "type": "text", "text": "What is in this image?" },
      { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "<base64>" } }
    ]
  }
]

system string | object[] 선택

시스템 프롬프트입니다. 문자열 또는 text 블록 배열입니다. 길고 변하지 않는 접두부를 캐시하려면 블록에 cache_control을 넣으세요.

예시

[
  {
    "type": "text",
    "text": "<long, stable instructions>",
    "cache_control": { "type": "ephemeral" }
  }
]

stream boolean 선택기본값: false

답변을 서버 전송 이벤트로 반환합니다. 아래 스트리밍 섹션을 참고하세요.

기본값: false

stop_sequences string[] 선택

생성을 멈추는 사용자 지정 문자열입니다. 이때 응답에는 stop_reason: "stop_sequence"가 있습니다.

tools object[] 선택

모델이 호출할 수 있는 도구입니다. 각각 name, description, input_schema(JSON Schema)를 가집니다. 모델이 도구를 호출하면 답변에 stop_reason: "tool_use"가 있으니, 도구를 실행하고 그 결과를 이어지는 tool_result 블록으로 반환하세요.

예시

[
  {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "input_schema": {
      "type": "object",
      "properties": { "city": { "type": "string" } },
      "required": ["city"]
    }
  }
]

tool_choice object 선택

모델이 tools를 사용해야 하는지, 어떻게 사용해야 하는지 정합니다.

허용 값: {"type":"auto"}, {"type":"any"}, {"type":"tool","name":"..."}, {"type":"none"}

• auto는 모델이 판단하고, any는 도구 중 하나를 강제하며, tool은 지정한 도구를 강제하고, none은 도구 사용을 금지합니다.

예시

{ "type": "auto" }
{ "type": "tool", "name": "get_weather" }

thinking object 선택

확장 사고입니다. type으로 켜고 끕니다. 사고 토큰은 max_tokens에 포함되며 출력 토큰으로 과금됩니다.

허용 값: adaptive, enabled, disabled

• thinking.type은 위 값 중 하나입니다. enabled는 thinking.budget_tokens(1,024 이상이고 max_tokens보다 작은 정수)를 받습니다.
• thinking.display는 summarized 또는 omitted입니다. 최신 모델은 summarized를 요청하지 않으면 사고 텍스트를 반환하지 않을 수 있습니다.
• 적응형 사고의 깊이는 output_config.effort로 설정하세요.

모델별

• claude-fable-5-2: {"type":"adaptive"}를 사용하고 output_config.effort로 깊이를 설정하세요. 적응형 사고가 항상 켜져 있으며, 끄거나 수동 budget_tokens를 설정할 수 없습니다.
• claude-fable-5-1: {"type":"adaptive"}를 사용하고 output_config.effort로 깊이를 설정하세요. budget_tokens는 거부됩니다.
• claude-opus-5-5: {"type":"adaptive"}를 사용하고 output_config.effort로 깊이를 설정하세요. budget_tokens는 거부됩니다.
• claude-sonnet-5-5: {"type":"adaptive"}를 사용하고 output_config.effort로 깊이를 설정하세요. budget_tokens는 거부됩니다.

예시

{
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "high" }
}

output_config.effort string 선택

모델이 추론하는 양입니다. high로 시작한 다음, 실제 워크로드에서 한 단계 낮은 값과 높은 값을 평가해 보세요.

허용 값: low, medium, high, xhigh, max

cache_control object 선택

프롬프트 캐싱입니다. system, messages 또는 tools 블록에 넣으면 그 블록까지 모두 캐시하며, 요청 최상위에 넣을 수도 있습니다. ttl은 5m(기본값) 또는 1h입니다.

허용 값: {"type":"ephemeral"}

• 캐시 읽기, 5분 캐시 쓰기, 1시간 캐시 쓰기는 따로 계량됩니다. 캐시된 접두부는 새 입력이 아니라 캐시 읽기로 과금됩니다.
• 캐시 적중 수는 usage.cache_read_input_tokens와 usage.cache_creation_input_tokens에 있습니다.

예시

{ "type": "ephemeral" }
{ "type": "ephemeral", "ttl": "1h" }