튜토리얼

grok-4.6 API 사용 방법: cURL, Python 및 실제로 작동하는 요청

hiapi의 OpenAI 호환 채팅 완성 엔드포인트에서 스트리밍 출력, 도구 호출, JSON 모드 사용하기

Sep 24, 2026

grok-4.6은 추론 튜닝된 채팅 모델로, hiapi API를 통해 사용할 수 있습니다. hiapi의 이미지·비디오 모델과 달리 비동기 /v1/tasks 파이프라인을 사용하지 않습니다. 즉, 동기식 OpenAI 호환 채팅 완성 인터페이스이므로 폴링 없이 일반 HTTP 응답(또는 SSE 스트림)을 곧바로 받습니다. 이 글에서는 최소한의 동작하는 요청을 먼저 소개한 뒤, 프로덕션 환경에서 실제로 필요한 부분인 스트리밍 출력, 도구 호출, JSON 모드, 오류 처리를 설명합니다.

필요한 준비물

hiapi API 키. 아직 없다면 콘솔에서 발급받으세요. 아래 모든 요청은 Authorization: Bearer sk-... 헤더에 이 키를 담아 보내야 합니다.
아무 HTTP 클라이언트나 사용 가능합니다. 예제에서는 curl과 Python의 requests를 사용하며, 어떤 언어를 쓰든 JSON 구조는 동일합니다.
SDK는 필요하지 않습니다. grok-4.6의 요청/응답 형식은 OpenAI 채팅 완성 규약에 매우 가깝기 때문에 OpenAI 호환 도구가 대개 그대로 작동합니다. 다만 hiapi는 전용 엔드포인트가 아니라 자체 채팅 완성 엔드포인트를 제공하므로, 클라이언트를 https://api.hiapi.ai/v1/chat/completions로 향하게 하고 모델 ID는 그대로 grok-4.6을 사용하세요.

최소한의 동작하는 요청

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "user", "content": "칼만 필터의 역할을 한 문장으로 설명해 줘."}
    ]
  }'

성공 응답은 다음과 같습니다:

{
  "id": "b6c018d3-218e-9b06-aa12-5afc02e21b5c",
  "object": "chat.completion",
  "model": "grok-4.6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "칼만 필터는 노이즈가 섞인 측정값과 예측 모델을 결합하고, 각자의 불확실성에 따라 가중치를 부여하여 시간에 따라 변하는 시스템의 실제 상태를 추정합니다."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 31,
    "total_tokens": 55
  }
}

답변 텍스트는 여느 OpenAI 스타일 채팅 API와 마찬가지로 choices[0].message.content에 있습니다.

다음은 requests를 사용한 동일한 호출을 Python으로 작성한 코드입니다:

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [
            {"role": "user", "content": "칼만 필터의 역할을 한 문장으로 설명해 줘."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

grok-4.6의 추론 조절 항목

grok-4.6은 추론 모델입니다. 최종 답변을 작성하기 전에 추가 토큰을 들여 '사고'하며, 이 추론 토큰은 출력 토큰으로 과금됩니다(현재 요율은 가격 참조). reasoning_effort로 사고량을 제어할 수 있으며, 값은 low, medium, high, xhigh 중 하나입니다(생략하면 API는 기본값으로 high를 사용):

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "다섯 단어로 인사해 줘."}],
    "reasoning_effort": "low"
  }'

비스리밍 응답에서는 모델의 추론 흔적이 message.reasoning_content에 제공되며, 최종 message.content와 분리되어 있습니다. 짧고 지연에 민감한 작업에는 low 또는 medium으로 낮추고, 다단계 문제에는 high 또는 xhigh가 지연과 토큰을 대가로 더 나은 답변을 제공합니다.

스트리밍 응답

"stream": true를 설정하면 전체 완성을 기다리지 않고 Server-Sent Events 형식으로 응답을 읽습니다:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "1부터 5까지 세어 줘."}],
    "stream": true
  }'

각 줄은 data: {...} 데이터 블록입니다. 추론 토큰은 choices[0].delta.reasoning_content를 통해 스트리밍되고, 이어서 답변 토큰은 choices[0].delta.content를 통해 스트리밍되며, 스트림은 리터럴 data: [DONE]으로 끝납니다:

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"reasoning_content":"나열"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"1, 2"},"finish_reason":null}]}

data: {"id":"...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Python에서는 requests로 스트림을 한 줄씩 반복할 수 있습니다:

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "grok-4.6",
        "messages": [{"role": "user", "content": "1부터 5까지 세어 줘."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        payload = line[len(b"data: "):]
        if payload == b"[DONE]":
            break
        chunk = json.loads(payload)
        delta = chunk["choices"][0]["delta"]
        if "content" in delta:
            print(delta["content"], end="", flush=True)

도구 호출

grok-4.6은 OpenAI 스타일 함수 호출을 지원합니다. tools 배열을 전달하고 tool_choice: "auto"를 지정하면 모델이 언제 어떤 도구를 호출할지 스스로 결정합니다.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [{"role": "user", "content": "도쿄 날씨는 어때?"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "특정 도시의 현재 날씨를 가져옵니다",
          "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

모델이 해당 도구를 호출하기로 결정하면 finish_reason에 "tool_calls"가 반환되고, 인수는 JSON 문자열 형태로 도착하므로 직접 파싱해야 합니다:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "tool_calls": [
          {
            "id": "call_...",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Tokyo\"}"}
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

함수를 실행한 뒤 실행 결과와 일치하는 tool_call_id를 담은 role: "tool" 메시지를 messages에 추가하고 대화를 다시 보내면, 최종 자연어 답변을 받을 수 있습니다.

JSON 모드

도구 호출 왕복 없이 응답을 파싱하고 싶다면 response_format을 설정하세요:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.6",
    "messages": [
      {"role": "system", "content": "\"city\"와 \"country\" 두 키를 가진 JSON 객체로 답하세요."},
      {"role": "user", "content": "에펠탑은 어디에 있나요?"}
    ],
    "response_format": {"type": "json_object"}
  }'

message.content는 (여전히 일반적인 채팅 완성 봉투 안에 담긴) JSON 문자열 형태로 반환되며, 클라이언트 쪽에서 json.loads(...)로 파싱하면 됩니다. 프롬프트에서 모델이 실제로 JSON을 생성하도록 반드시 지시하세요. response_format은 출력 형식을 제약할 뿐 스키마를 대신 만들어 주지는 않습니다.

프로덕션 환경 실무

문서화된 오류 코드를 처리하세요. 키가 잘못되었거나 누락되면 HTTP 401이 반환되고 응답 본문은 {"error":{"code":"permission_denied","message":"...","request_id":"...","type":"hiapi_error"}}입니다. 잔액 부족은 402, 잘못된 모델 ID나 파라미터 형식 오류는 400입니다. 상태 코드를 먼저 확인하고 오류 응답 본문의 request_id를 기록하세요. 문제를 보고해야 할 때 바로 이 정보를 사용하게 됩니다.
429와 503에는 백오프 재시도를 적용하세요. hiapi는 계정 단위로 속도 제한을 적용합니다. 429는 한도를 초과했다는 뜻이고, 503은 모델을 일시적으로 사용할 수 없다는 뜻입니다. 둘 다 촘촘한 재시도 루프보다는 상한이 있는 지수 백오프 재시도(예: 1초, 2초, 4초 후 몇 차례 시도 후 포기)에 적합합니다.
요청 타임아웃을 설정하세요. high 또는 xhigh 추론 강도에서는 low보다 확연히 오래 걸리므로, 단일 전역 상수가 아닌 사용 중인 강도 수준에 맞춰 클라이언트 타임아웃을 설정하세요.
사용자에게 노출되는 모든 시나리오에서는 스트리밍 출력을 우선하세요. 비스트리밍 호출은 전체 응답(모든 추론 토큰 포함)이 준비될 때까지 블로킹됩니다. 스트리밍 출력은 첫 토큰을 즉시 UI에 전달하고, reasoning_content 증분이 최종 답변보다 먼저 도착할 때 '생각 중' 상태를 표시할 수 있게 해 줍니다.
키를 하드코딩하지 마세요. 환경 변수나 시크릿 관리자에서 로드하고, 소스 코드 저장소에서 읽지 마세요. 위 예제가 바로 그 이유 때문에 $HIAPI_API_KEY / os.environ["HIAPI_API_KEY"]에서 읽는 것입니다.

전체 파라미터 참조(grok-4.6이 허용하는 모든 필드 포함)는 모델 페이지와 grok-4.6 문서를 참조하세요.

자주 묻는 질문

hiapi의 grok-4.6은 OpenAI SDK와 호환되나요? 요청과 응답 구조는 OpenAI 채팅 완성 규약(messages, choices[0].message.content, 스트리밍 증분, 도구 호출)을 따르므로, 기본 URL과 모델 ID를 덮어쓸 수 있는 대다수 OpenAI 호환 도구가 대개 작동합니다. 기본 URL을 https://api.hiapi.ai/v1로 지정하고 모델 ID로 grok-4.6을 사용하세요.

왜 다른 모델보다 응답이 느린가요? grok-4.6은 답변 전에 내부 추론을 위해 토큰을 소모하며, 이 토큰은 출력 토큰으로 과금됩니다. 지연에 민감한 호출에서는 reasoning_effort를 low 또는 medium으로 낮추거나, 전체 응답을 한 번에 기다리지 않도록 스트리밍 출력으로 전환하세요.

reasoning_content는 무엇이며 사용자에게 숨겨도 되나요? 모델의 중간 추론 흔적으로, content와 분리되어 반환됩니다(스트리밍 시에는 delta.reasoning_content 형태로 반환). UI에서 렌더링하지 않아도 전혀 문제없습니다. 최종 답변은 content뿐입니다.

401과 permission_denied가 발생했습니다. 무엇이 잘못된 건가요? Authorization 헤더가 누락되었거나 형식이 잘못되었거나, 키가 유효하지 않거나 폐기된 경우입니다. Authorization: Bearer sk-...를 올바르게 보냈는지, 콘솔의 유효한 키를 사용하는지 다시 확인하세요.

grok-4.6의 함수 호출과 JSON 모드를 하나의 요청에서 함께 사용할 수 있나요? tools/tool_choice와 response_format은 서로 독립적인 파라미터라 동시에 설정할 수 있습니다. 다만 모델이 도구 호출을 결정하면 해당 턴의 finish_reason은 "tool_calls"가 되고 message.content는 비어 있을 수 있으므로, 먼저 도구 호출을 처리한 뒤 후속 턴에서 최종 JSON 형식 답변을 요청하세요.

비용은 어떻게 관리하나요? 추론 토큰은 출력 토큰에 포함되므로 비용은 reasoning_effort와 응답 길이에 따라 달라집니다. 고부하 작업을 실행하기 전에 가격 페이지에서 현재 토큰당 요율을 확인하세요.