튜토리얼
HiAPI의 Gemini-4 Argon 및 Carbon: curl, Python과 실행 가능한 요청
gemini-4-argon, gemini-4-carbon, gemini-4-carbon@vertex 중에서 선택하는 개발자를 위한 실용 통합 가이드
이 페이지에서
코드를 작성하기 전에 Gemini-4 변형부터 선택하세요
모든 Gemini-4 통합에서 첫 번째 결정은 curl이냐 Python이냐가 아니라 어떤 모델 ID를 전송하느냐입니다. HiAPI에서 gemini-4-argon, gemini-4-carbon, gemini-4-carbon@vertex는 서로 다른 세 가지 라우팅 대상이며, model 필드에 전달하는 문자열이 어느 백엔드가 요청을 처리할지 결정합니다. 미리 선택해 두면 작동할 수 없는 요청 본문을 디버깅하는 수고를 덜 수 있습니다.
실제로 마주하는 세 가지 대상
gemini-4-argon—— 자체 모델 ID를 가진 독립적인 Gemini-4 변형입니다. 별칭이 아니라 그 자체의 모델로 취급하세요. 동작, 지연 시간 특성, 출력 특성이 Carbon과 다를 수 있습니다.gemini-4-carbon—— HiAPI 표준 라우팅에서의 기본 Carbon 대상입니다.gemini-4-carbon@vertex—— 동일한 Carbon 계열이지만 Vertex 기반 라우팅으로 제공됩니다.@vertex접미사는 별도 파라미터가 아니라 모델 ID 자체의 일부입니다.
선택 방법
워크로드에서 출발하세요. Gemini-4를 폭넓게 평가 중이라면 gemini-4-argon과 gemini-4-carbon에 동일한 프롬프트를 각각 실행하고 결과를 비교한 뒤 결정하세요. Vertex 라우팅이 정말로 필요하다면(예: 팀이 이미 운영 중인 환경과 일치하기 때문), 곧바로 gemini-4-carbon@vertex를 대상으로 지정하세요.
실용적인 요점: 세 가지 모두 동일한 요청 구조를 사용합니다. 변형 선택은 한 줄만 바꾸는 일이므로, 실행 가능한 요청을 확보한 뒤에 최종 결정을 내려도 됩니다. 모델 카드를 먼저 보고 싶다면 gemini-4-argon과 gemini-4-carbon을 참고하세요.
이 가이드의 예시는 전부 gemini-4-carbon을 사용합니다. 어떤 변형을 따라 하려면 해당 ID만 교체하면 됩니다.
자격 증명과 기본 URL 준비
어떤 요청 본문이든 중요해지기 전에 세 가지가 먼저 올바라야 합니다: 기본 URL, API 키, 인증 헤더 형식. 대부분의 첫 요청 실패는 이 셋 중 하나에서 발생합니다.
필요한 것
- API 키 하나, HiAPI 계정 대시보드에서 발급받습니다. 기밀로 취급하세요——소스 파일에 붙여 넣지 말고 환경 변수에서 불러오세요.
- HiAPI 기본 URL. 모든 모델 호출은 동일한 호스트로 전송되며, 모델 변형은 경로가 아니라
model필드로 선택됩니다. - 모든 요청에 두 개의 헤더가 필요합니다:
Authorization: Bearer $HIAPI_API_KEYContent-Type: application/json
환경 설정하기
export HIAPI_API_KEY="your-key-here"
그런 다음 코드를 작성하기 전에 셸이 이를 볼 수 있는지 확인하세요:
echo "${HIAPI_API_KEY:0:4}..."
아무것도 출력되지 않으면 키가 현재 셸에 내보내지지 않은 것이며, 모든 요청이 인증 오류로 실패합니다. 클라이언트가 아니라 여기서 고치세요.
반복해서 사용할 요청 구조
아래의 모든 예시는 model 문자열과 messages 배열을 담은 JSON 요청 본문을 전송합니다. 이 구조는 curl과 Python 사이, 비스트리밍과 스트리밍 사이, 그리고 모델 변형 사이에서도 변하지 않습니다. 구조를 안정적으로 유지하면 요청 본문을 복사하는 것만으로 코드를 이식할 수 있습니다.
바로 실행 가능한 curl 요청
다음은 복사해서 바로 붙여 넣을 수 있는 완전한 비스트리밍 호출입니다. 다른 무엇을 추가하기 전에 먼저 이것을 실행하세요——이 요청이 통과하면 키, 기본 URL, 헤더가 모두 올바르다는 뜻입니다.
curl -sS "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."}
]
}'
각 필드의 역할
model—— 변형 선택자입니다. 다른 변경 없이gemini-4-argon또는gemini-4-carbon@vertex로 바꾸면 다른 대상에 도달합니다.messages—— 순서가 있는 배열입니다. 역할은system,user,assistant입니다. 시스템 메시지를 사용한다면 맨 앞에 두세요.content—— 메시지 텍스트입니다. 단순한 텍스트 턴의 경우 일반 문자열입니다.
응답 본문 읽기
응답은 모델의 답변과 토큰 사용량 같은 메타데이터를 담은 JSON 객체입니다. 비스트리밍이므로 전체 본문이 한 번에 도착하고 curl은 출력 후 종료됩니다. 메시지 답변이 포함된 파싱 가능한 JSON 객체를 받았다면 요청은 통한 것입니다——이후의 모든 내용은 이 기준선 위에 쌓입니다.
빠른 상태 점검: 출력을 JSON 포매터(| jq .)로 넘기면 응답 구조를 한 줄의 긴 텍스트가 아니라 명확하게 읽을 수 있습니다.
Python으로 같은 요청 보내기
Python 버전도 요청 본문은 완전히 동일하게 유지됩니다——전송 방식만 바뀝니다. requests를 사용하세요:
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gemini-4-carbon",
"messages": [
{"role": "system", "content": "You are a concise technical assistant."},
{"role": "user", "content": "Explain what an idempotency key is in two sentences."},
],
}
response = requests.post(
f"{base_url}/chat/completions",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])
curl 호출과 정확히 대응되는 이유
payload가 이전 섹션의 JSON 요청 본문과 바이트 단위로 동일하다는 점에 주목하세요. json= 파라미터가 이를 직렬화하고 Content-Type을 대신 설정하며, 헤더 딕셔너리가 인증을 제공합니다. 모델, 메시지, 역할 모두 변하지 않습니다.
유지할 만한 두 가지 습관
- 타임아웃을 설정하세요. 타임아웃이 없으면 연결이 멈출 때 프로세스가 무한정 대기합니다. 비스트리밍 호출에는
timeout=60이 합리적인 출발점입니다. - 응답 본문을 읽기 전에
raise_for_status()를 호출하세요. 실패한 요청은 완성 결과가 아니라 구조화된 오류 객체를 반환합니다——4xx에서json()을 검사하면 오해하게 됩니다. 먼저 예외가 발생하게 두고, 그다음 응답 텍스트를 기록하세요.
요청 본문을 함수나 작은 설정 객체에 담아 두면 스트리밍과 도구 호출 부분이 이를 복사하지 않고 확장할 수 있습니다.
호출에 스트리밍 지원 추가하기
먼저 비스트리밍 요청을 통과시키세요. 그런 다음 스트리밍을 활성화하세요——실패 양상이 다르므로 두 변경을 동시에 겹치면 오류를 구분하기 어려워집니다.
스트리밍 켜기
기존 요청 본문에 필드를 하나 추가하세요:
{
"model": "gemini-4-carbon",
"stream": true,
"messages": [
{"role": "user", "content": "List three uses for a message queue."}
]
}
프로토콜 변경은 이게 전부입니다. 서버는 이제 하나의 JSON 문서 대신 이벤트 스트림을 반환합니다.
스트림을 올바르게 소비하기
핵심 규칙: 스트리밍 응답에 .json()을 호출하지 마세요. 본문이 단일 JSON 객체가 아니므로 파싱 오류가 발생합니다. requests를 사용할 때는 줄 단위로 반복하며 각 청크를 개별적으로 파싱하세요:
import json, os, requests
response = requests.post(
f"{os.environ['HIAPI_BASE_URL']}/chat/completions",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "gemini-4-carbon",
"stream": True,
"messages": [{"role": "user", "content": "List three uses for a message queue."}],
},
stream=True,
timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
if not line:
continue
decoded = line.decode("utf-8")
if decoded.startswith("data: "):
decoded = decoded[len("data: "):]
if decoded.strip() == "[DONE]":
break
try:
chunk = json.loads(decoded)
except json.JSONDecodeError:
continue
print(chunk)
주의할 점
requests에stream=True를 전달하세요. 그렇지 않으면 클라이언트가 전체 응답 본문을 먼저 버퍼링한 뒤에야 한 줄을 보게 되어 목적에 어긋납니다.- 빈 줄과 JSON이 아닌 keep-alive 메시지를 건너뛰세요. 위의
try/except는 의도된 것입니다——스트림에는 청크로 파싱할 수 없는 줄이 포함될 수 있습니다. - 청크에 걸쳐 텍스트를 누적하세요. 각 청크는 전체 답변이 아니라 조각을 담고 있습니다. 텍스트 델타가 도착하는 대로 이어 붙이세요.
스트리밍이 작동하면 비스트리밍 테스트에서 stream을 다시 false로 되돌려 도구 호출을 읽기 쉽게 유지하세요. Carbon 대상에 대한 개요는 gemini-4-carbon 모델 페이지가 좋은 참고점입니다.
요청 본문에 도구 호출 추가하기
도구 호출은 두 군데에서 요청을 바꿉니다: 도구를 선언하고, 텍스트 대신 도구 호출 요청을 담을 수 있는 응답 턴을 처리합니다. 이 기능은 비스트리밍 텍스트 호출이 통과한 뒤에만 추가하세요.
도구 선언하기
model과 messages 옆에 tools 배열을 추가하세요. 각 도구에는 이름, 설명, 그리고 해당 파라미터의 JSON 스키마가 있습니다. 설명은 중요합니다——모델이 해당 도구를 호출할지 판단하는 근거이기 때문입니다.
{
"model": "gemini-4-carbon",
"messages": [
{"role": "user", "content": "What is the weather in Lisbon?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Return current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
}
]
}
도구 호출 루프
도구를 사용하는 요청은 단일 호출이 아니라 대화입니다:
- 사용자 메시지와 도구 선언을 전송합니다.
- 어시스턴트 턴을 검사합니다. 도구 호출 파라미터가 포함되어 있으면 모델이 무언가를 실행하길 원하는 것입니다.
- 로컬 함수를 실행합니다——HiAPI는 여러분의 코드를 실행하지 않습니다.
- 두 개의 메시지를 추가합니다: 어시스턴트의 도구 호출 턴, 그리고 일치하는 호출 ID에 연결된 함수 결과를 담은
tool역할 메시지. - 전체 메시지 기록을 다시 전송합니다. 이제 모델이 최종 답변을 생성합니다.
도구 특유의 실패 지점
- 스키마 불일치.
parameters스키마가 특정 필드를 필수로 표시했는데 결과에 해당 필드가 빠지면 이후 턴이 거부될 수 있습니다. 스키마를 정확하게 유지하세요. - 기록 누락. 다시 전송할 때마다 원래 사용자 메시지와 도구 호출 턴을 모두 포함해야 합니다——도구 결과만 보내면 안 됩니다.
- 스트리밍 + 도구. 도구 호출 파라미터가 여러 스트림 청크에 나뉘어 도착할 수 있습니다. 흐름을 익히는 동안에는
stream: false로 도구를 실행하여 각 턴이 읽기 쉬운 객체로 도착하게 하세요.
클라이언트를 다시 작성하지 않고 모델과 제공자 전환하기
모델 변형이 요청 본문의 문자열에 불과하므로 대상 전환은 리팩터링이 아니라 구성 변경입니다. 클라이언트가 모델 ID를 변수에서 읽도록 설계하세요——환경 변수, 설정 파일, CLI 플래그——여러 곳에 하드코딩하지 마세요.
전환 자체
export HIAPI_MODEL="gemini-4-carbon" # default
export HIAPI_MODEL="gemini-4-argon" # different variant
export HIAPI_MODEL="gemini-4-carbon@vertex" # Vertex-backed Carbon
코드에서는 요청 본문에서 해당 변수를 참조하세요:
payload = {
"model": os.environ["HIAPI_MODEL"],
"messages": messages,
}
@vertex 접미사는 모델 문자열과 함께 전달됩니다. 별도 필드로 분리하거나 제거하지 마세요——라우팅 가능한 ID의 일부이며, 제거하면 조용히 비Vertex 대상으로 라우팅됩니다.
전환 후 다시 테스트할 항목
- 일반 텍스트 턴 —— ID가 인식되고 인증이 여전히 유효한지 확인합니다.
- 가장 긴 실제 프롬프트 —— 변형마다 긴 입력이나 구조화된 입력을 처리하는 방식이 다를 수 있습니다. 잘림과 형식을 검증하세요.
- 스트리밍 —— 청크 리듬과 경계가 대상에 따라 다를 수 있으므로 스트리밍 경로를 다시 실행하세요.
- 도구 호출 —— 전체 도구 호출 루프를 다시 검증하세요. 파라미터 형식이 변형 차이를 가장 자주 드러내는 부분입니다.
현재 설정된 HIAPI_MODEL에 대해 이 네 가지 검사를 실행하는 작은 스모크 테스트 스크립트를 유지하세요. 그러면 제공자 전환이 디버깅 세션이 아니라 구성 변경과 명령 한 번이 됩니다.
흔한 요청 실패 문제 해결하기
거의 모든 통합 실패는 몇 가지 범주로 나눌 수 있습니다. 증상을 맞추고 수정을 적용한 뒤, 다른 무엇이든 바꾸기 전에 비스트리밍 기준선을 다시 실행하세요.
인증과 라우팅
- 401 또는 403. 키가 없거나, 만료되었거나, 접두사가 잘못되었습니다. 헤더가 정확히
Authorization: Bearer <key>인지(사이에 공백 하나만) 확인하고, 변수가 실제로 코드를 실행하는 셸이나 프로세스에 내보내졌는지 확인하세요. 앞 몇 글자를 출력해 확인하세요. - 엔드포인트가 404 반환. 기본 URL이 잘못되었거나 경로 세그먼트가 중복되었습니다. 모델은 URL이 아니라 요청 본문에 들어갑니다.
- 모델을 찾을 수 없음. 모델 ID에 오타가 있습니다.
gemini-4-argon,gemini-4-carbon,gemini-4-carbon@vertex를 글자 하나하나 대조하세요——@vertex접미사를 가장 자주 빠뜨립니다.
요청 본문 문제
- 스키마 메시지와 함께 400. 보통
messages형식 오류입니다:role누락, 문자열이어야 할content가 그렇지 않음, 또는 빈 배열. 이 가이드의 가장 작은 두 줄짜리 요청 본문에서 시작해 필드를 하나씩 추가하세요. - 도구 추가 후 400.
parameters스키마가 유효한 JSON 스키마가 아니거나, 도구 결과 턴이 어시스턴트 메시지의 호출 ID와 일치하지 않습니다. 전체 응답 본문을 기록하세요——오류 텍스트가 문제 필드를 지목합니다.
스트리밍 실패
- 응답에서 JSON 파싱 오류. 스트림에
.json()을 호출했습니다. 줄 단위로 반복하며 각 청크를 파싱하고 빈 줄과[DONE]표시를 건너뛰세요. - 응답이 한 번에 도착. 클라이언트 호출에서
stream=True를 설정하지 않아requests가 전체 응답 본문을 버퍼링했습니다. - 출력이 잘림. 루프가 조기에 중단되었습니다——보통 빈 줄이나 keep-alive 메시지에서 발생합니다. 명시적인 스트림 종료 표시에서만 중단하세요.
디버깅 원칙
구축할 때와 같은 순서로 이분 탐색하세요: 인증과 헤더, 그다음 비스트리밍 텍스트, 그다음 스트리밍, 그다음 도구. 각 계층마다 실패 특성이 다르므로 마지막으로 변경한 것이 거의 항상 원인입니다. 실패할 때마다 HTTP 상태와 전체 응답 본문을 기록하세요——메시지가 보통 구체적인 필드를 지목합니다.
먼저 gemini-4-argon 또는 gemini-4-carbon에서 기준선을 통과시킨 뒤 거기서부터 요청 본문을 확장하세요. 어떤 변형이 워크로드에 맞는지 아직 결정 중이라면 gemini-4-argon 모델 페이지가 시작점입니다.