Grok API 키 발급 및 첫 호출 방법 (Grok 4.6)

Grok API 키는 xAI가 개발자 콘솔에서 발급하는 자격 증명으로, 코드가 HTTPS를 통해 Grok 모델을 호출할 수 있게 해줍니다. 한 번 생성하여 모든 요청에 Bearer 토큰으로 전송하면, xAI는 사용한 토큰을 팀의 선불 크레딧에서 차감합니다. 이 개념이 생소하다면, API 키란 무엇인가가 기본 사항을 다루고 있으며, 이 가이드는 오늘 당장 키를 사용하고자 하는 개발자를 위한 것입니다.

절차는 다음과 같습니다: console.x.ai에서 키를 생성하고, curl로 한 번, Python으로 한 번 요청을 보낸 다음, Apidog로 키를 옮겨 안전하게 저장하고, 셸에 붙여넣지 않고 요청을 보내며, 첫 요청을 저장된 테스트로 전환하는 것입니다. 현재 주력 모델은 grok-4.6이며, 아래의 모든 예시는 이 모델을 사용합니다.

button

시작하기 전에 필요한 것

xAI 계정. console.x.ai에서 가입하세요.

계정에 크레딧이 있어야 합니다. 콘솔은 선불 크레딧으로 운영되며, 공식 빠른 시작 가이드는 가입 직후 크레딧을 충전하도록 안내합니다. 잔액이 0이면 요청이 거부됩니다.
curl (macOS 및 대부분의 Linux 배포판에 포함) 및 pip가 설치된 Python 3.9 이상.
요청을 저장하고, 테스트하고, 공유하려면 Apidog. 무료 플랜은 4명의 사용자를 지원하며, 소규모 팀에 충분합니다. 4단계 전에 Apidog를 다운로드하세요.

1단계: xAI 콘솔에서 키 생성

로그인하고 결제를 엽니다. API 지출 관리에서 카드로 크레딧을 구매하거나(즉시 반영됨) 은행 송금(결제 문서에 따라 2~3영업일 소요)으로 구매합니다.
API 키 페이지를 엽니다. 빠른 시작 가이드에서는 console.x.ai/team/default/api-keys에 링크되어 있습니다. team 부분이 중요합니다. 키는 개인 로그인에 속하지 않고 팀에 속합니다.
API 키 생성을 클릭하고 6개월 후에도 알아볼 수 있는 이름을 지정합니다. "key1"보다는 "apidog-local-dev"가 좋습니다.
생성되는 즉시 키를 복사합니다. 이 값을 전체적으로 볼 수 있는 유일한 시간이라고 생각하십시오.
코드에 저장하는 대신 환경 변수로 저장합니다.

export XAI_API_KEY="paste-your-key-here"

XAI_API_KEY는 공식 문서에서 사용하는 변수 이름이므로, xAI 자체 SDK 및 대부분의 커뮤니티 통합은 추가 구성 없이 이를 인식합니다.

환경별로 하나의 키를 사용하는 것이 좋은 습관입니다. 로컬 개발, CI 및 프로덕션에 별도의 키를 사용하면 노트북 키가 유출되었을 때 다른 것에 영향을 주지 않고 삭제할 수 있습니다.

2단계: curl로 첫 호출하기

xAI의 주요 텍스트 엔드포인트는 POST https://api.x.ai/v1/responses입니다. 키는 Authorization 헤더에, JSON은 본문에, 모델 ID는 model 필드에 전송합니다.

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "instructions": "You are a senior backend engineer. Answer in three sentences.",
    "input": "My API returns 429 to a client that retries instantly. What should the client change?"
  }'

성공적인 응답은 output 배열을 가진 JSON입니다. 텍스트는 "type": "output_text"와 함께 output[].content[].text에 있으며, usage 객체는 input_tokens, output_tokens, total_tokens는 물론 추론 및 캐시된 토큰에 대한 세부 정보를 보고합니다. 이러한 사용량 숫자는 청구 기준이 되므로, 첫날부터 기록해두세요.

알아두면 좋은 두 가지 세부 사항:

instructions는 시스템 프롬프트입니다. 채팅 형태를 선호한다면 input을 {role, content} 메시지 배열로 전달할 수도 있습니다.
기존 OpenAI 스타일 코드가 있는 경우, POST https://api.x.ai/v1/chat/completions는 동일한 키와 모델 ID로 여전히 작동합니다. xAI는 이를 레거시 엔드포인트로 분류하고 새로운 기능을 Responses에 먼저 제공하므로, 새로운 프로젝트는 /v1/responses에서 시작하십시오.

이 동일한 엔드포인트에서 스트리밍, 도구 호출 및 이미지 입력에 대해서는 Grok 4.6 API 사용 방법을 참조하세요.

3단계: Python에서 동일하게 호출하기

xAI의 REST API는 OpenAI SDK와 호환되므로, 새로운 클라이언트 라이브러리가 필요하지 않습니다. base_url을 xAI로 지정하고 환경에서 키를 읽으세요.

import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.6",
    instructions="You are a senior backend engineer. Answer in three sentences.",
    input="My API returns 429 to a client that retries instantly. What should the client change?",
)

print(response.output_text)
print(response.usage.input_tokens, response.usage.output_tokens)

pip install openai로 SDK를 설치하십시오. os.environ["XAI_API_KEY"]를 읽으면 변수가 없을 경우 명확한 KeyError가 발생하므로, 빈 Bearer 헤더를 보내고 401 오류를 디버깅하는 것보다 낫습니다.

xAI는 또한 gRPC 전송과 컬렉션 및 음성 API와 같은 추가 기능을 갖춘 네이티브 Python SDK (xai-sdk)를 게시합니다. 첫 호출의 경우 OpenAI 클라이언트가 더 짧은 경로입니다.

4단계: Apidog에 키 저장 및 테스트

터미널에 키를 한 번 붙여넣는 것은 작동합니다. 팀원과 요청을 공유하고, 모델 업데이트 후 다시 실행하거나, CI에 넣는 것이 API 클라이언트의 역할이 빛을 발하는 곳입니다. Apidog에서의 흐름은 다음과 같습니다.

키를 로컬 값으로 저장합니다. 환경(Environments)을 열고 "xAI"라는 이름으로 하나를 생성한 다음, 두 개의 변수를 추가합니다. 하나는 공유 값 https://api.x.ai/v1을 가진 baseUrl이고, 다른 하나는 플레이스홀더를 공유 값으로, 실제 키를 로컬 값으로 가진 XAI_API_KEY입니다. 공유 값은 팀원과 동기화되지만, 로컬 값은 사용자 컴퓨터의 클라이언트 캐시에 남아 Apidog 서버에 도달하지 않습니다. 변수 이름은 프로젝트와 함께 제공되지만, 비밀은 그렇지 않습니다. Apidog 환경 및 비밀 변수는 CI가 자체 키를 주입하는 방법을 포함하여 공유 값과 로컬 값의 차이를 자세히 다룹니다.

첫 요청을 보냅니다. 새 엔드포인트 POST {{baseUrl}}/responses를 생성합니다. 인증(Auth) 탭에서 Bearer Token을 선택하고 {{XAI_API_KEY}}를 입력합니다. 2단계의 JSON 본문을 붙여넣고 xAI 환경을 선택한 다음 보내기(Send)를 누릅니다. 응답 패널에는 상태, 시간 및 파싱된 본문이 표시되므로, 원본 JSON을 읽는 대신 output 및 usage를 클릭하여 확인할 수 있습니다.

테스트로 저장합니다. 후처리(Post Processors)에서 Assert 단계를 추가합니다: 상태 코드(status code)가 200인지, $.model이 grok-4.6과 같은지 JSONPath로 확인합니다. $.usage.output_tokens가 0보다 큰지 두 번째 단언(assertion)을 추가합니다. 엔드포인트를 저장하고, 테스트(Tests)를 열고, 테스트 시나리오를 생성한 다음, 엔드포인트를 가져옵니다. 그 이후로는 한 번의 클릭으로 호출을 다시 실행하고 키, 모델 ID 및 응답 형식이 여전히 작동하는지 알려줍니다.

선택 사항: 모의(Mock) 응답. 실제 응답을 엔드포인트의 예제로 저장하고 Apidog의 모의(Mock) URL로 전환합니다. 프런트엔드 작업 및 단위 테스트는 크레딧을 소비하거나 속도 제한에 도달하지 않고 가짜 Grok 응답에 대해 실행할 수 있습니다.

제한, 크레딧 및 가격

결제. 크레딧은 팀별로 선불로 지불됩니다. 잔액이 설정한 임계값(충전당 최소 $5) 이하로 떨어지면 자동 충전으로 더 구매할 수 있으며, 월별 한도와 해당 한도의 80%에 도달하면 경고가 표시됩니다. 월별 인보이스 발행이 가능하지만 기본적으로 비활성화되어 있으며 xAI 영업팀을 통해 진행됩니다. 기본 $0 인보이스 한도에서는 선불 크레딧이 소진되는 순간 요청이 거부됩니다.

공식 가격 페이지에 따른 백만 토큰당 Grok 4.6 가격:

프롬프트 크기	입력	캐시된 입력	출력
200k 토큰 미만	$2.00	$0.50	$6.00
200k 토큰 이상	$4.00	$1.00	$12.00

컨텍스트 창은 500k 토큰입니다. 프롬프트가 200k 임계값을 초과하는 요청은 초과된 부분뿐만 아니라 모든 토큰에 대해 더 높은 요율로 청구됩니다.

속도 제한. xAI는 초당 요청 및 분당 토큰을 제한합니다. 이 수치는 티어에 따라 달라집니다. 5개 티어(0부터 4까지)와 엔터프라이즈 티어가 있으며, 2026년 1월 1일부터 누적 지출에 따라 자동으로 잠금 해제되며 티어는 절대로 하향되지 않습니다. 팀의 현재 제한은 콘솔의 모델 페이지에서 확인할 수 있습니다. 추론 토큰과 캐시된 프롬프트 토큰을 포함하여 모든 토큰은 TPM에 포함됩니다.

무료 크레딧. xAI 문서는 선불 모델을 설명하며 API에 대한 상시 무료 티어를 광고하지 않습니다. 프로모션 크레딧은 때때로 콘솔에 나타났습니다. 블로그 게시물에 의존하기보다는 자신의 결제 페이지를 확인하십시오.

일반적인 오류 및 해결 방법

401 권한 없음 (Unauthorized). 키가 없거나, 형식이 잘못되었거나, 삭제되었습니다. 헤더에 Authorization: Bearer <key>가 한 칸 띄어서 읽히는지 확인하고, curl을 실행하는 셸에 $XAI_API_KEY가 설정되어 있는지(echo $XAI_API_KEY | wc -c가 1보다 큰 값을 출력해야 함), 그리고 키가 콘솔에 여전히 존재하는지 확인하십시오. 복사-붙여넣기 시 뒤에 남는 줄 바꿈이 일반적인 원인입니다.

403 금지됨 (Forbidden). 키는 유효하지만 요청한 작업을 수행할 권한이 없습니다. 가능한 원인: 키 또는 팀이 차단되었거나, $0 인보이스 한도로 크레딧이 소진되었거나, 팀이 해당 모델에 액세스할 수 없습니다. 먼저 결제(Billing)를 확인한 다음, API 키 페이지에서 키를 확인하십시오.

429 요청 과다 (Too Many Requests). 해당 티어의 RPS 또는 TPM 한도에 도달했습니다. 지터(jitter)가 포함된 지수 백오프(exponential backoff)를 추가하고, 동시성을 제한하고, 프롬프트 크기를 줄이고, 대량 작업을 배치(Batch) API로 이동하십시오. 하루 종일 한도에 걸려 있다면, 코드 수정보다는 티어 업그레이드(spend tier)가 해결책입니다.

400 잘못된 요청 (Bad Request). 일반적으로 잘못된 모델 ID(grok-4-6이 아닌 grok-4.6) 또는 유효하지 않은 JSON입니다. 오류 본문에 필드 이름이 명시됩니다.

스트리밍 및 도구 호출 실패를 포함하여 이러한 응답을 읽는 방법에 대한 자세한 내용은 Grok 4.6 API 요청을 테스트하고 디버깅하는 방법에 있습니다.

자주 묻는 질문

무료 Grok API 키가 있나요?

문서화된 상시 제공은 없습니다. API는 선불 크레딧으로 운영되며, 빠른 시작 가이드에서는 첫 호출 전에 크레딧을 충전하도록 안내합니다. Grok을 기반으로 구축하는 것보다 Grok을 시도하는 것이 목표라면, Grok을 무료로 사용하는 방법이 키가 필요 없는 소비자 경로를 다룹니다.

Grok API 키가 OpenAI SDK와 함께 작동하나요?

네, 작동합니다. base_url="https://api.x.ai/v1"로 설정하고 xAI 키를 api_key로 전달하세요. client.responses.create()와 레거시 client.chat.completions.create() 모두 model="grok-4.6"으로 작동합니다.

요청에 어떤 모델 ID를 넣어야 하나요?

주력 모델은 grok-4.6입니다. 별칭 grok-4.6-latest는 최신 개정판을 추적합니다. grok-4.5 및 grok-4.3과 같은 이전 ID는 자체 가격으로 계속 나열되지만, 새로운 작업은 4.6으로 시작해야 합니다.

키가 유출되면 어떻게 해야 하나요?

API 키 페이지에서 즉시 삭제하고, 새 키를 생성한 다음, 사용되는 모든 곳에서 환경 변수를 업데이트하십시오. 그런 다음 저장소 및 CI 로그에서 이전 값을 검색하십시오. Apidog의 엔터프라이즈 플랜에서는 Secret Scanner가 요청, 변수, 스크립트 및 문서에 있는 키를 표시하여, 누군가가 로컬 값이 아닌 공유 값에 키를 붙여넣은 경우를 감지합니다.

다음 단계

이제 작동하는 Grok API 키, 성공적인 curl 및 Python 호출, 그리고 Apidog에 반복 가능한 테스트로 저장된 요청을 갖게 되었습니다. 실제 프롬프트에 해당 테스트를 적용하고 usage 숫자를 확인하면, 프로덕션 트래픽이 발생하기 전에 지출 및 속도 제한 여유를 알 수 있습니다.