Grok API: 내 코드에서 Grok 호출하기

코드에서 Grok을 호출하는 두 가지 방법

개발자가 Grok 모델을 호출하는 방법은 크게 두 가지가 있어요. 첫 번째는 console.x.ai에서 발급받은 키를 사용하는 공식 xAI API(현재 SpaceXSI 브랜드)예요. 두 번째는 하나의 키와 통합 결제로 여러 제공업체의 모델을 연결해 주는 OpenRouter 같은 모델 라우터를 이용하는 방법이죠. 두 방식 모두 OpenAI의 Chat Completions 포맷을 지원하므로, 엔드포인트 주소와 모델명만 바꾸면 공식 OpenAI SDK를 그대로 쓸 수 있어요.

어떤 방식을 선택해야 할까요?

• xAI API: 모든 최신 Grok 기능을 가장 먼저 써보고 싶을 때 추천해요. 전체 모델 라인업, Responses API, 서버 측 웹 검색 및 X 검색 도구, Grok Imagine을 통한 이미지 및 영상 생성, 음성, 배치 작업, 프롬프트 캐싱 할인 등을 지원해요. 베이스 URL은 https://api.x.ai/v1이에요.
• OpenRouter: 별도의 계약 없이 Grok과 다른 기업들의 모델을 손쉽게 오가며 쓰고 싶거나, 이미 OpenRouter 계정이 있는 경우에 적합해요. 베이스 URL은 https://openrouter.ai/api/v1이며, 모델 ID 앞에 x-ai/ 접두사가 붙어요. 설정 방법은 OpenRouter 퀵스타트를 참고하세요.

어떤 방식을 고르든 API 키는 반드시 서버나 환경 변수에 안전하게 보관하세요. 누구나 코드를 열어볼 수 있는 웹페이지나 모바일 앱 클라이언트 코드에 직접 넣어서 배포하면 안 돼요.

xAI API로 첫 요청 보내기

콘솔에서 API 키를 생성한 뒤 XAI_API_KEY로 저장하고, Grok 4.7에 첫 메시지를 보내보세요.

curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "reasoning_effort": "low",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give me three tips for a first marathon."}
    ]
  }'

Python (OpenAI 라이브러리 사용)

import os
from openai import OpenAI

grok = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

answer = grok.chat.completions.create(
    model="grok-4.3",
    reasoning_effort="medium",
    messages=[{"role": "user", "content": "Is 391 a prime number? Show your check."}],
)
print(answer.choices[0].message.content)

reasoning_effort는 답변을 내놓기 전 모델이 고민하는 시간(사고 강도)을 조절해요. Grok 4.3은 none, low, medium, high, xhigh를 지원하며 기본값은 low예요. Grok 4.7은 low, medium, high, xhigh를 지원하며 기본값은 high예요. Grok 4.20의 경우, xAI는 grok-4.20-0309-reasoning과 grok-4.20-0309-non-reasoning이라는 별도 ID로 나누어 제공하고 있어요.

OpenRouter를 이용한 동일한 호출

OpenRouter에서는 키를 OPENROUTER_API_KEY에 저장하고 x-ai/ 접두사가 붙은 모델 ID를 사용해요. OpenRouter에서는 사고 강도를 reasoning 객체로 제어해요. 다음 자바스크립트 코드는 Node.js 18 이상 버전에서 바로 실행할 수 있어요.

const endpoint = "https://openrouter.ai/api/v1/chat/completions";

const reply = await fetch(endpoint, {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    model: "x-ai/grok-4.20",
    reasoning: { enabled: false },
    stream: false,
    messages: [{ role: "user", content: "Rewrite this headline in a calmer tone: PRICES EXPLODE AGAIN" }],
  }),
});
const json = await reply.json();
console.log(json.choices[0].message.content);

모델이 스스로 생각한 뒤 답변하게 하려면 reasoning: { effort: "low" }(또는 medium, high) 형태로 지정하면 돼요. 사고 과정을 거치되 결과 텍스트에는 포함하지 않으려면 exclude: true를 추가하세요. stream: true를 설정하면 답변이 생성되는 즉시 받아볼 수 있어 채팅 인터페이스에서 체감 속도가 훨씬 빨라져요.

이미지 입력 전송하기

Grok 4.20, 4.3, 4.7은 모두 멀티모달 이미지 입력을 지원해요. OpenAI 스타일처럼 메시지 안에 콘텐츠 배열을 담아 보내면 돼요. xAI 공식 문서에 따르면 최대 20MiB 크기의 JPEG 및 PNG 이미지를 지원하며, 공개 웹 URL과 base64 데이터 URL을 모두 쓸 수 있어요.

{
  "model": "grok-4.20-0309-non-reasoning",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
      {"type": "text", "text": "List the items and the total on this receipt."}
    ]
  }]
}

Grok 모델 ID 및 요금 안내

다음은 OpenRouter에 등록된 SpaceXAI의 주요 텍스트 모델 목록과 컨텍스트 크기, 100만 토큰당 요금이에요(2026년 10월 OpenRouter 정가 기준). xAI API 역시 20만 토큰 미만의 프롬프트에 대해서는 기본 요금이 동일해요.

xAI의 모델 및 가격 안내 페이지에 명시된 주요 세부사항은 다음과 같아요(2026년 10월 xAI 정가 기준).

• 긴 프롬프트는 추가 요금이 붙어요: 프롬프트 길이가 20만 토큰에 도달하면 요청 전체에 더 높은 요금이 적용돼요. Grok 4.7은 $4 / $12, Grok 4.3 및 4.20은 $2.50 / $5로 청구돼요.
• 캐시된 입력 할인: 반복되는 프롬프트 접두사의 경우, Grok 4.7은 100만 토큰당 $0.50, Grok 4.3 및 4.20은 $0.20의 할인 단가가 적용돼요.
• 배치(Batch) 작업 할인: 즉각적인 응답이 필요 없는 대량 작업은 할인을 받을 수 있으며, OpenRouter에서도 x-ai/grok-4.3:batch를 $1 / $2에 제공해요.
• 플랫폼별 컨텍스트 표기 차이: OpenRouter에서는 Grok 4.20의 컨텍스트를 2,000,000토큰으로 안내하는 반면, xAI 공식 페이지에는 1,000,000토큰으로 표기되어 있어요.

생각하는 과정에서 쓰이는 추론(Thinking) 토큰도 출력 토큰으로 청구되므로, 추론 모델을 쓰면 단순 토큰 단가로 계산했을 때보다 요청당 비용이 더 나올 수 있어요.

실전 개발 팁

• 일반 작업에는 Grok 4.20 non-reasoning으로 시작해 보세요: 챗봇, 문장 다듬기, 데이터 추출용으로 매우 빠르고 경제적이에요. 속도보다 복잡한 문제 해결 품질이 더 중요할 때 Grok 4.3이나 4.7로 넘어가시는 걸 추천해요.
• 지식 컷오프 시점을 확인하세요: xAI에 따르면 Grok 4.7의 학습 데이터는 2026년 5월까지예요. 그 이후의 정보가 필요하다면 프롬프트에 직접 최신 정보를 넣어주거나, 호출당 과금되는 xAI의 서버 측 웹 및 X 검색 도구를 활용하세요.
• 시스템 메시지를 구체적으로 작성하세요: 원하는 역할, 어조, 출력 형식을 시스템 프롬프트에 명확히 지정해 두세요. 코드로 결과를 파싱할 계획이라면 스키마를 지정해 JSON 출력을 요구하는 편이 안전해요.
• 속도 제한(Rate Limit) 예외를 처리하세요: API 호출 중 429 응답이 오면 잠시 대기한 뒤 재시도하도록 백오프 로직을 구현해 두는 것이 좋아요.
• 이용 정책을 준수하세요: API 호출 시에도 xAI의 사용 정책이 그대로 적용돼요. 최종 사용자별로 요청을 구분하고 모니터링하려면 safety_identifier 필드를 적극 활용해 보세요.

오류가 발생했을 때 확인 사항

• 401 또는 403 오류: API 키가 누락되었거나, 만료되었거나, 잘못된 환경 변수를 참조하고 있을 수 있어요. 서버 로그에 키의 앞 글자 몇 자리를 출력해 정상적으로 로드되었는지 확인해 보세요.
• Model not found (모델을 찾을 수 없음): 모델명 접두사를 확인하세요. OpenRouter는 x-ai/grok-4.7 형태여야 하고, xAI API는 접두사 없이 grok-4.7이어야 해요.
• 빈 응답이나 지나치게 느린 응답: 추론 모델의 경우 생각하는 데 너무 많은 토큰을 소모했을 가능성이 커요. 추론 강도를 낮추거나 max_tokens 한도를 늘려보세요.
• 이미지 업로드 실패: 파일 포맷을 JPEG나 PNG로 변환하고 제한 용량(20MiB)을 넘지 않는지 확인하세요.

자주 묻는 질문 (FAQ)

Grok API는 OpenAI SDK와 호환되나요?

네, 호환돼요. OpenAI SDK에서 엔드포인트 주소를 xAI 키와 함께 https://api.x.ai/v1로 지정하거나, OpenRouter 키와 함께 OpenRouter 주소로 설정한 뒤 Grok 모델 ID를 입력하면 바로 동작해요.

무료로 쓸 수 있는 Grok API가 있나요?

영구적인 무료 티어는 제공되지 않아요. xAI와 OpenRouter 모두 토큰당 요금을 청구하지만, 가벼운 테스트 수준이라면 비용 부담은 매우 적은 편이에요.

Grok API로 이미지를 생성할 수 있나요?

네, 별도의 이미지 전용 엔드포인트에서 xAI의 Grok Imagine 모델을 사용하면 가능해요. 자세한 내용은 저희 Grok Imagine 페이지를 참고하세요. 웹사이트 내 Grok.Online 채팅에서는 이미지 생성을 지원하지 않아요.

Grok.Online은 어떤 Grok 모델을 사용하나요?

저희 웹 채팅 서비스는 OpenRouter를 통해 추론 기능이 꺼진 Grok 4.20, 낮은 사고 강도로 설정된 Grok 4.3, 그리고 하루 최대 10회까지 쓸 수 있는 Grok 4.7을 제공하고 있어요.