xAI의 Grok 모델을 애플리케이션에 연동하는 작업은 표준 REST 프로토콜 및 OpenAI SDK와의 완벽한 호환성 덕분에 매우 신속하게 진행할 수 있습니다. Grok API는 https://api.x.ai/v1 기본 주소에서 실행되며, 표준 Bearer 토큰 인증을 통해 플래그십 추론 모델인 grok-4.7이나 초고속 코딩 모델인 grok-build-0.1을 자유롭게 호출할 수 있습니다. 또한 멀티턴 함수 호출(Function Calling / Tool Calling)을 통해 사내 데이터베이스, 내부 마이크로서비스 및 외부 API와 Grok을 매끄럽게 연결할 수 있습니다.
본 가이드에서는 API 키 발급 및 설정, 워크로드에 최적화된 모델 엔드포인트 선정, 그리고 프로덕션 레벨의 함수 호출 구현 방법을 단계별로 정리합니다.
1. 인증 설정 및 API 키 관리
Grok API의 모든 접근 권한은 xAI 콘솔(https://console.x.ai)에서 중앙 집중식으로 관리됩니다.
1단계: API 키 생성
- xAI Console에 접속하여 회원가입 또는 로그인을 완료합니다.
- Billing(결제) 메뉴에서 크레딧을 충전하여 API 사용 잔액을 준비합니다.
- API Keys 페이지(
https://console.x.ai/team/default/api-keys)로 이동한 후 Create API Key 버튼을 클릭합니다. - 생성된 키를 즉시 복사하여 안전한 비밀 관리소에 저장합니다(모달 창을 닫으면 콘솔에서 키가 다시 표시되지 않습니다).
2단계: 환경 변수 구성
API 키는 소스 코드에 직접 하드코딩하지 않고 XAI_API_KEY 환경 변수로 지정하는 것이 안전합니다.
export XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Node.js 또는 Python 프로젝트에서는 루트 디렉터리의 .env 파일에 기록합니다.
XAI_API_KEY=xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3단계: 클라이언트 SDK 초기화
xAI는 OpenAI REST 규격을 수용하므로 공식 xai-sdk뿐만 아니라 범용 openai 라이브러리, Vercel AI SDK 등을 폭넓게 활용할 수 있습니다.
Python (공식 openai 라이브러리 사용):
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
)
Python (네이티브 xai-sdk 사용):
import os
from xai_sdk import Client
client = Client(api_key=os.getenv("XAI_API_KEY"))
Node.js / TypeScript (openai 패키지 사용):
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.XAI_API_KEY,
baseURL: "https://api.x.ai/v1",
});
2. 모델 엔드포인트 및 아키텍처 선정
실제 애플리케이션을 구성할 때는 HTTP 엔드포인트 인터페이스와 요구 조건에 부합하는 모델을 정확히 매핑해야 합니다.
엔드포인트 인터페이스: /v1/responses vs /v1/chat/completions
https://api.x.ai/v1/responses(권장 최신 엔드포인트): 에이전트(Agentic) 워크플로를 위해 특화된 엔드포인트로, 구조화된 입력 배열,previous_response_id기반의 멀티턴 상태 관리, 서버 측 검색 도구와의 통합 오케스트레이션을 기본 지원합니다.https://api.x.ai/v1/chat/completions(OpenAI 호환 엔드포인트): 업계 표준 Chat Completions 규격과 동일하여 기존 파이프라인의baseURL과apiKey만 교체하면 즉시 연동할 수 있습니다.
언어 및 추론 모델 비교
| 모델명 / 에일리어스 | 컨텍스트 윈도우 | 최적 사용 시나리오 | 요금 (100만 토큰 기준) |
|---|---|---|---|
grok-4.7 (grok-4.7-latest) | 500,000 tokens | 플래그십 추론 모델. 복잡한 에이전트 분기, 심층 코드 분석, 다중 도구 연동에 최적화되었으며 추론 강도(low, medium, high, xhigh) 설정 지원. | 입력 $2.00 / 출력 $6.00 (캐시 입력 $0.50) |
grok-build-0.1 (grok-code-fast-1) | 256,000 tokens | 코드 작성 및 자동완성에 특화된 초고속 저지연 모델. 인라인 자동완성, 코드 리팩터링, 단위 테스트 자동화에 적합. | 입력 $1.00 / 출력 $2.00 (캐시 입력 $0.20) |
grok-4.3 (grok-4.3-latest) | 1,000,000 tokens | 100만 토큰의 초대형 컨텍스트 창을 지원하여 대규모 코드베이스 전체 분석이나 방대한 문서 질의응답을 경제적으로 처리. | 입력 $1.25 / 출력 $2.50 (캐시 입력 $0.20) |
grok-4.20-multi-agent-0309 | 1,000,000 tokens | 다중 에이전트 간의 협업 및 분산 상태 합의 처리에 최적화된 아키텍처. | 입력 $1.25 / 출력 $2.50 (캐시 입력 $0.20) |
참고: 텍스트 외에도 실시간 음성 대화를 지원하는 grok-voice-think-fast-2.0(Voice API) 및 이미지/비디오 생성을 위한 grok-imagine-image-2.0(Imagine API) 등 전용 멀티모달 엔드포인트가 제공됩니다.
3. 함수 호출(Function Calling / Tool Calling) 구현
함수 호출은 모델이 추론 과정에서 직접 결정을 내리고 외부 도구를 활용할 수 있게 해줍니다. 정적 지식에 머무르지 않고, JSON 규격에 맞춘 인자값을 생성하여 개발자의 애플리케이션 로직을 실행하도록 위임합니다.
도구 호출 실행 주기
- 도구 정의: 요청 시 JSON Schema 규격을 만족하는 도구 목록(
name,description,parameters)을 모델에 전달합니다. - 모델 평가: Grok이 사용자 질의를 분석하여 외부 함수 호출이 필요한지 판단합니다.
- 호출 요청 발행: 모델은 텍스트 생성을 멈추고 함수 이름과 파라미터 JSON이 포함된
tool_calls객체를 반환합니다. - 로컬 실행: 애플리케이션에서 파라미터를 파싱하여 로컬 함수나 내부 API를 실행합니다.
- 결과 피드백 및 응답 생성: 실행 결과를 Grok에 다시 전달하면, 모델이 해당 데이터를 종합하여 최종 사용자 응답을 생성합니다.
전체 구현 코드 예시 (Python + OpenAI 클라이언트)
다음은 responses 엔드포인트를 활용하여 계정 조회 도구를 정의하고, Grok의 호출 요청을 받아 실행한 뒤 결과를 전달하는 전체 코드입니다.
import os
import json
from openai import OpenAI
# 1. 클라이언트 초기화
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
)
# 2. JSON Schema 규격에 맞춘 도구 선언
tools = [
{
"type": "function",
"name": "fetch_user_account",
"description": "계정 ID를 기반으로 고객 프로필, 구독 플랜 등급, 현재 계정 상태를 조회합니다.",
"parameters": {
"type": "object",
"properties": {
"account_id": {
"type": "string",
"description": "사용자 고유 계정 식별자 (예: 'usr_10294')"
},
"include_usage_stats": {
"type": "boolean",
"description": "현재 청구 주기의 토큰 사용량 데이터를 포함할지 여부",
"default": False
}
},
"required": ["account_id"]
}
}
]
# 로컬 백엔드 비즈니스 로직 모의 구현
def execute_fetch_user_account(account_id: str, include_usage_stats: bool = False):
return {
"account_id": account_id,
"name": "Alex Mercer",
"tier": "Enterprise",
"status": "Active",
"usage_tokens": 1420500 if include_usage_stats else None
}
# 3. 도구 정의를 포함한 초기 질문 전달
user_query = "usr_10294 사용자의 계정 정보를 조회해서 현재 유효한 Enterprise 등급인지 확인해 주세요."
response = client.responses.create(
model="grok-4.7",
input=[{"role": "user", "content": user_query}],
tools=tools,
)
# 4. 모델의 함수 호출 요청 디스패치
for item in response.output:
if item.type == "function_call":
func_name = item.name
func_args = json.loads(item.arguments)
call_id = item.call_id
print(f"모델이 도구 호출을 요청함: {func_name}, 인자값: {func_args}")
if func_name == "fetch_user_account":
tool_result = execute_fetch_user_account(**func_args)
# 5. 도구 실행 결과를 모델에 피드백하여 추론 재개
followup = client.responses.create(
model="grok-4.7",
input=[{
"type": "function_call_output",
"call_id": call_id,
"output": json.dumps(tool_result)
}],
tools=tools,
previous_response_id=response.id,
)
# 종합된 최종 답변 출력
for followup_item in followup.output:
if followup_item.type == "message":
print("\n최종 답변:\n", followup_item.content[0].text)
4. 실무 도입 시 필수 고려사항 및 고급 기능
Grok 기반의 함수 호출 시스템을 프로덕션에 배포할 때 유의해야 할 아키텍처 규칙은 다음과 같습니다.
- 파라미터 루트 스키마 제약: 도구의
parameters필드 루트 타입은 반드시"type": "object"(또는 하위 항목이 모두 object인oneOf/anyOf)이어야 합니다. 스칼라나 배열을 루트로 직접 선언하면 HTTP 400 유효성 검사 에러가 발생합니다. - 병렬 함수 호출(Parallel Function Calling): Grok은 기본적으로 병렬 도구 호출을 지원합니다. 한 번의 질문에서 여러 개의 독립 데이터를 요구할 경우 단일 응답에 복수의 함수 호출을 포함할 수 있습니다. 순차 실행이 필요한 경우 페이로드에
parallel_tool_calls: false를 지정합니다. - 도구 선택 정책 제어(
tool_choice):"auto"(기본값): 모델이 텍스트 답변과 도구 호출 여부를 자율 결정."required": 최소 1개 이상의 도구 호출을 강제."none": 해당 턴에서 도구 호출 비활성화.{"type": "function", "function": {"name": "fetch_user_account"}}: 특정 함수만 호출하도록 고정.
- 내장 도구와 커스텀 도구의 하이브리드 결합: Grok은 xAI의 서버 관리형 내장 도구(
{"type": "web_search"}웹 검색,{"type": "x_search"}X 검색)와 클라이언트 측 커스텀 함수를 동일 요청 안에서 함께 운용할 수 있습니다. 서버 도구는 xAI 인프라에서 자동 수행되며, 커스텀 함수만 클라이언트 측으로 위임됩니다. - 단일 청크 스트리밍: 스트리밍(Streaming) 환경에서 Grok은 함수 호출 메타데이터를 여러 조각으로 쪼개지 않고 단일 청크로 완결성 있게 전달하므로, 클라이언트 측에서 불완전한 JSON 조각을 재조립할 필요가 없습니다.