Gemini Messages

BeatAPI 키 하나로 Anthropic Messages 형식에서 Gemini 4 Argon, Gemini 4 Carbon, Gemini 3.8 Flash, Gemini 3.1 Pro를 호출합니다.

• 현재 모든 Gemini 모델이 엔드포인트 POST /v1/messages 하나를 사용합니다. model만 바꿔 전환하세요.
• 스트리밍과 도구 사용. gemini-4-argon은 이미지와 긴 영상도 이해합니다.
• Anthropic SDK와 호환됩니다. 기본 URL을 바꾸고 BeatAPI 키를 사용하세요. 모든 요청에 anthropic-version 헤더를 보내세요.
• tool_choice는 모델에 전달되지만 모든 모델이 적용하지는 않으며, thinking은 효과가 없습니다. 아래 파라미터 레퍼런스를 참고하세요.

API Explorer에서 이 엔드포인트를 엽니다. BeatAPI API 키를 입력하고 전송하세요. 실제 호출이며 본인 잔액에서 과금됩니다.

모델

model에 다음 ID 중 하나를 보내세요. 각각 별개의 모델이며, 서로의 별칭으로 취급하지 마세요.

• 가격은 할인이 적용된 기본 등급입니다. 롱 컨텍스트 등급, 캐시 입력 요금, 캐시 쓰기는 이 표에 없습니다. 가격표를 참고하세요.
• —는 카탈로그에서 해당 수치를 공개하지 않는다는 뜻입니다.

이 계열의 이전 ID도 계속 동작하며 레거시 모델에 나와 있습니다.

빠른 시작

서버에 @anthropic-ai/sdk 또는 anthropic 패키지를 설치하고 키는 BEATAPI_API_KEY에 보관하세요. 브라우저 코드에는 절대 넣지 마세요. SDK가 anthropic-version 헤더를 자동으로 보냅니다. 아래는 요청 예시이며 실제로 기록된 모델 출력이 아닙니다.

content의 text 블록에서 답변을 읽은 다음 stop_reason과 usage를 확인하세요. HTTP 200만으로는 답변이 작업 요구를 충족한다고 볼 수 없으니 애플리케이션에서 검증하세요. 텍스트 요청은 바로 반환되므로 /v1/tasks를 폴링하지 마세요.

curl --request POST \
  --url https://direct.beatapi.io/v1/messages \
  --header "x-api-key: $BEATAPI_API_KEY" \
  --header 'anthropic-version: 2023-06-01' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.8-flash",
  "max_tokens": 2000,
  "messages": [
    {
      "role": "user",
      "content": "Design a resilient webhook retry strategy for a payments API."
    }
  ]
}'

엔드포인트와 인증

POST https://direct.beatapi.io/v1/messages

모든 요청에 anthropic-version 헤더(예: 2023-06-01)를 보내세요. Anthropic SDK는 자동으로 추가합니다. 인증에는 x-api-key와 Authorization: Bearer <BEATAPI_API_KEY> 모두 사용할 수 있습니다.

요청 파라미터

요청은 Anthropic Messages 형식을 사용합니다. 아래 레퍼런스에서 각 필드의 동작을 설명합니다. thinking은 받지만 결과에 영향을 주지 않습니다. 이 페이지에 없는 필드는 효과가 있다고 보장하지 않습니다.

응답

스트리밍하지 않는 호출은 JSON 객체 하나를 반환합니다. 아래는 축약한 예시입니다.

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "gemini-3.8-flash",
  "content": [
    {
      "type": "text",
      "text": "Retry with exponential backoff and jitter, and make every handler idempotent."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 19,
    "output_tokens": 16
  }
}

응답 필드

스트리밍

"stream": true를 설정하세요. 스트림은 message_start로 시작해 message_stop으로 끝납니다. 그 사이의 블록은 content_block_start, content_block_delta, content_block_stop 이벤트로 도착하며, message_delta에 stop_reason이 담겨 있습니다.

• 응답은 text/event-stream이며, 스트리밍하지 않으면 application/json입니다.
• 텍스트는 text_delta 이벤트로 도착합니다. 추론 모델은 텍스트 블록 앞에 thinking_delta 이벤트가 있는 thinking 블록을 보냅니다. 도구 인수는 input_json_delta 이벤트로 도착합니다.
• 모델 호출 전에 발생한 실패는 스트림 이벤트가 아니라 HTTP 상태와 함께 일반 JSON 오류로 반환됩니다.
• 명시적인 시간 제한을 설정하고, 스트리밍 응답은 안전하게 다시 연결하세요.

event: message_start
data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[],"usage":{"input_tokens":19,"output_tokens":1}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Retry"}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" with backoff"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":16}}
event: message_stop
data: {"type":"message_stop"}

오류

HTTP 오류 요약

인증, 라우팅, 요청 속도 제한, 알 수 없는 모델 실패는 모델 호출 전에 BeatAPI 오류 형식(error.code, error.message, retryable, request_id)으로 응답합니다. 그 밖의 모든 실패는 Anthropic 형식 {"type": "error", "error": {"type", "message"}}를 유지하며, 코드는 error.type에 있고 요청 id는 message로 끝납니다. 오류를 참고하세요.

전체 코드 표와 재시도 정책: 오류.

참고

• Gemini 모델은 Chat Completions, OpenAI Responses, Gemini 네이티브에서도 응답합니다.
• Gemini 모델은 기본적으로 추론하며 사고 토큰을 출력으로 과금하므로, max_tokens는 답변뿐 아니라 사고까지 고려해 잡으세요.
• 캐시 입력은 더 낮은 요금으로 과금됩니다. gemini-4-argon과 gemini-4-carbon은 입력 가격의 1/20, gemini-3.8-flash와 gemini-3.1-pro-preview는 1/10입니다. 별도의 캐시 저장 요금은 없습니다. 캐시 적중을 가정하지 말고 usage의 캐시 입력 수를 확인하세요. gemini-3.1-pro-preview 프롬프트가 200,000토큰을 넘으면 요청 전체에 상위 등급 요금이 적용됩니다. 가격표를 참고하세요.
• 모든 요청에 anthropic-version을 보내세요. thinking에 의존하지 마세요. 효과가 없습니다.
• API 키는 신뢰할 수 있는 서버에 두고, 응답의 요청 ID를 기록하며, 429, 500, 503만 재시도하세요.