hiapi API를 통해 Claude Sonnet 4.6을 사용하는 방법

구축하게 될 내용

실행 가능한 통합 예제: hiapi의 OpenAI 호환 Chat Completions API를 통해 Claude Sonnet 4.6을 호출합니다——단일 요청으로 실제 완성 결과를 반환하며, 데모가 정상 동작한 후 실제로 사용하게 될 프로덕션급 패턴(스트리밍 출력, 도구 호출, 적응형 사고)도 함께 다룹니다.

사전 조건: hiapi API 키 하나. 콘솔에서 발급받으세요——이것은 sk-... 문자열이며, 동일한 키가 이 모델뿐 아니라 계정에서 활성화된 모든 모델에 공통으로 사용됩니다.

아래의 모든 내용은 작성 시점에 라이브 API에 대해 실제로 실행하여 검증했습니다.

최소 실행 예제

Claude Sonnet 4.6은 표준 Chat Completions 엔드포인트의 텍스트 모델입니다——hiapi가 이미지/비디오/오디오 모델에 사용하는 비동기 /v1/tasks 흐름이 아닙니다. 요청 한 번, 응답 한 번, 폴링이 필요 없습니다.

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
    ]
  }'

응답(일부 발췌):

{
  "id": "msg_bdrk_011Cf8Bo25qCVFFQF5ETk8Wf",
  "model": "claude-sonnet-4-6",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 13, "completion_tokens": 4, "total_tokens": 17 }
}

동일한 호출을 requests만 사용해 Python으로 구현하면 다음과 같습니다:

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-sonnet-4-6",
        "messages": [
            {"role": "user", "content": "Explain how an HTTP cache works in three short paragraphs."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

OpenAI와 구조가 호환되므로 이 코드는 수정 없이 공식 openai Python/JS SDK와도 함께 사용할 수 있습니다——base_url을 https://api.hiapi.ai/v1로 지정하고 hiapi 키를 전달하기만 하면 됩니다.

프로덕션급 패턴

스트리밍 출력

"stream": true를 설정하고 Server-Sent Events를 읽습니다. 각 데이터 블록에는 delta.content 조각이 담겨 있습니다. 스트림은 마지막 데이터 블록에서 finish_reason: "stop"으로 끝나고, 이어서 [DONE] 센티널이 옵니다:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true
  }'

data: {"choices":[{"delta":{"content":"","role":"assistant"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":"Here"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{"content":" you"},"finish_reason":null,"index":0}]}

data: {"choices":[{"delta":{},"finish_reason":"stop","index":0}]}

data: [DONE]

데이터 블록 전반에 걸쳐 choices[0].delta.content를 누적하면 전체 텍스트를 재구성할 수 있습니다.

도구 호출

OpenAI와 동일한 방식으로 함수를 선언한 다음, 다음 턴에서 어시스턴트의 tool_calls 메시지와 tool 결과 메시지를 다시 보냅니다:

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_task_status",
        "description": "Look up a task by ID.",
        "parameters": {
          "type": "object",
          "properties": {"task_id": {"type": "string"}},
          "required": ["task_id"],
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

응답은 finish_reason: "tool_calls"를 반환하며, 함수 이름과 JSON으로 인코딩된 인자는 choices[0].message.tool_calls에 위치합니다. 로컬에서 함수를 실행한 다음, 다음 요청에서 일치하는 tool_call_id와 함께 role: "tool" 메시지로 결과를 보내면——모델이 그 지점부터 이어서 진행합니다.

적응형 사고

Claude Sonnet 4.6은 선택적으로 활성화하는 추론 단계를 지원합니다. "thinking": {"type": "adaptive"}를 추가하고 output_config.effort로 노력 수준(low, medium, high, max)을 선택하세요:

{
  "model": "claude-sonnet-4-6",
  "messages": [{"role": "user", "content": "Compare two approaches and state the trade-offs."}],
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "high"}
}

사람이 읽을 수 있는 추론 궤적은 choices[0].message.reasoning_content를 통해 반환됩니다; 원시 reasoning_details 배열은 서명 메타데이터를 담고 있으며, 대화를 이어가거나 도구 호출로 넘어가야 하는 경우 원본 그대로 보존해야 합니다——파싱하거나 표시하거나 추측하지 말고, 다음 요청에 그대로 전달하기만 하세요.

오류 처리

인증 실패 시 hiapi_error 오류 봉투와 함께 HTTP 401이 반환됩니다:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again.",
    "type": "hiapi_error"
  }
}

response.json()["choices"]에 접근하기 전에 response.status_code를 먼저 확인하고, 에스컬레이션이 필요하면 error.request_id를 기록하세요——지원 팀이 이를 통해 특정 호출을 추적할 수 있습니다.

멱등성과 재시도

Chat Completions 호출은 /v1/tasks 작업처럼 요청 ID 기준으로 멱등하지 않습니다——재시도된 요청은 새로운 완성입니다. 프로덕션 트래픽의 경우 5xx/타임아웃에 대응해 자체 백오프 재시도로 호출을 감싸고, max_tokens 상한을 설정하여 재시도 폭풍으로 인한 무제한 청구를 방지하세요.

관련 문서

• Claude Sonnet 4.6 모델 참조——전체 매개변수 표, 응답 스키마, 그리고 hiapi 문서에서 직접 가져온 더 많은 요청 예제.
• 인증——hiapi API 키의 작동 방식과 교체 방법.
• hiapi 요금——Claude Sonnet 4.6 및 기타 모든 활성화된 모델의 실시간 토큰당 요율.

자주 묻는 질문

claude-sonnet-4-6이 제가 보내야 하는 정확한 모델 ID인가요? 네——model 필드에 순수 문자열 claude-sonnet-4-6을 보내세요. hiapi는 OpenAI 호환 인터페이스 뒤에서 이를 Anthropic의 Claude Sonnet 4.6으로 라우팅하므로 제공자별 접두사가 필요하지 않습니다.

hiapi 이미지 및 비디오 모델과 동일한 /v1/tasks 흐름을 사용하나요? 아니요. Claude Sonnet 4.6 같은 텍스트 모델은 동기식 POST /v1/chat/completions 엔드포인트를 사용합니다——요청 한 번, 응답 한 번(또는 SSE 스트림 하나). /v1/tasks는 비동기로 실행되고 폴링 가능한 URL 또는 콜백을 반환하는 미디어 모델(이미지, 비디오, 오디오) 전용입니다.

원시 curl/requests 대신 OpenAI SDK를 사용할 수 있나요? 네. 엔드포인트가 OpenAI와 호환되므로 공식 openai SDK의 base_url을 https://api.hiapi.ai/v1로 지정하고 hiapi 키를 api_key로 전달하면——기본 채팅, 스트리밍 출력 또는 도구 호출에 다른 코드 변경이 필요하지 않습니다.

Claude Sonnet 4.6은 이미지 입력을 지원하나요? 네, 콘텐츠 블록을 통해 지원합니다——메시지의 content를 배열로 설정하고, 그 안에 type: "image_url" 블록을 넣어 image_url.url이 공개 이미지 URL을 가리키도록 하면 텍스트 블록과 나란히 배치됩니다.

thinking을 생략하면 어떻게 되나요? 현재 버전에 따르면 적응형 사고는 선택적으로 활성화됩니다——thinking 필드를 생략하거나(thinking.type을 disabled로 설정) 모델이 직접 답변하며 응답에 reasoning_content가 포함되지 않습니다.

대규모 배치 작업을 실행하기 전에 현재 요금을 어디에서 확인할 수 있나요? hiapi의 요금 페이지에 Claude Sonnet 4.6의 실시간 토큰당 요율이 나와 있습니다——요율은 변경될 수 있고 이 문서는 구식이 될 수 있는 숫자를 하드코딩하지 않으므로, 예산을 수립하기 전에 확인하세요.