Gemini Responses

BeatAPI 키 하나로 OpenAI Responses API에서 Gemini 4 Argon, Gemini 4 Carbon, Gemini 3.8 Flash, Gemini 3.1 Pro를 호출합니다.

• 현재 모든 Gemini 모델이 엔드포인트 POST /v1/responses 하나를 사용합니다. model만 바꿔 전환하세요.
• 스트리밍과 함수 호출. gemini-4-argon은 이미지와 긴 영상도 이해합니다.
• OpenAI SDK와 호환됩니다. 기본 URL을 바꾸고 BeatAPI 키를 사용하세요. 기존 Chat Completions 연동은 Chat Completions를 참고하세요.
• 대화 상태는 서버에 저장되지 않습니다. 매 턴마다 전체 기록을 input에 담아 보내세요.

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

모델

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

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

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

빠른 시작

서버에 openai 패키지를 설치하고 키는 BEATAPI_API_KEY에 보관하세요. 브라우저 코드에는 절대 넣지 마세요. output_text는 답변 텍스트를 가져오는 SDK 단축 속성입니다. 아래는 요청 예시이며 실제로 기록된 모델 출력이 아닙니다.

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

curl --request POST \
  --url https://direct.beatapi.io/v1/responses \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gemini-3.8-flash",
  "max_output_tokens": 2000,
  "input": "Design a resilient webhook retry strategy for a payments API."
}'

엔드포인트와 인증

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

요청 파라미터

표준 OpenAI Responses 필드를 받습니다. 요청 형식이 호환된다고 해서 모든 모델별 옵션이나 호스팅 도구가 지원되는 것은 아니므로, 사용하는 옵션은 직접 테스트하세요.

응답

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

{
  "id": "resp_example",
  "object": "response",
  "model": "gemini-3.8-flash",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Retry with exponential backoff and jitter, and make every handler idempotent."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 19,
    "output_tokens": 16,
    "total_tokens": 35
  }
}

응답 필드

스트리밍

"stream": true를 설정하세요. 스트림은 response.created로 시작해 response.output_text.delta 이벤트로 답변을 전달하고 response.completed로 끝납니다.

• 응답은 text/event-stream이며, 스트리밍하지 않으면 application/json입니다.
• 함수 호출은 별도의 출력 항목으로 도착하며, 인수는 response.function_call_arguments.delta 이벤트로 스트리밍됩니다.
• 모델 호출 전에 발생한 실패는 스트림 이벤트가 아니라 HTTP 상태와 함께 일반 JSON 오류로 반환됩니다.
• 명시적인 시간 제한을 설정하고, 스트리밍 응답은 안전하게 다시 연결하세요.

event: response.created
data: {"type":"response.created","response":{"id":"resp_example","status":"in_progress"}}
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Retry"}
event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":" with backoff"}
event: response.completed
data: {"type":"response.completed","response":{"id":"resp_example","status":"completed"}}

오류

HTTP 오류 요약

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

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

참고

• Gemini 모델은 Chat Completions, Anthropic Messages, Gemini 네이티브에서도 응답합니다.
• Gemini 모델은 기본적으로 추론하며 사고 토큰을 출력으로 과금하므로, max_output_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토큰을 넘으면 요청 전체에 상위 등급 요금이 적용됩니다. 가격표를 참고하세요.
• API 키는 신뢰할 수 있는 서버에 두고, 응답의 요청 ID를 기록하며, 429, 500, 503만 재시도하세요.