HiAPI
Ko
블로그

튜토리얼

hiapi API를 통해 Claude Opus 4.8을 사용하는 방법

Sep 21, 2026
hiapi API를 통해 Claude Opus 4.8을 사용하는 방법

구축하게 될 것

hiapi의 OpenAI 호환 Chat Completions API를 통해 Claude Opus 4.8을 호출하는 실행 가능한 통합입니다. Claude Opus 4.8은 Anthropic의 현재 Claude 4.8 시리즈 중 최상위 모델입니다. 한 번의 요청으로 실제 완성을 반환하며, 데모가 작동한 후 필요한 프로덕션 패턴(스트리밍, 도구 호출, 적응형 사고)도 함께 다룹니다.

사전 요구사항: hiapi API 키가 필요합니다. 콘솔에서 발급받으세요. 이는 sk-... 문자열이며, 동일한 키가 이 모델에 국한되지 않고 계정에서 활성화된 모든 모델에 적용됩니다.

아래의 모든 내용은 작성 당시 실제 온라인 API에 대해 실제로 실행해 검증했습니다.

최소 실행 예제

Claude Opus 4.8은 표준 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-opus-4-8",
    "messages": [
      {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
    ],
    "max_tokens": 1024
  }'

응답(간략화):

{
  "id": "msg_011CfFm8abLRcYtLVSky81As",
  "model": "claude-opus-4-8",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14 }
}

같은 호출을 Python에서 requests만 사용해 수행:

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={"Authorization": "Bearer sk-<your-api-key>"},
    json={
        "model": "claude-opus-4-8",
        "messages": [
            {"role": "user", "content": "Review this function for edge cases and suggest a fix."}
        ],
        "max_tokens": 1024,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])
print(data["usage"])  # prompt_tokens / completion_tokens / total_tokens

모델 ID claude-opus-4-8을 그대로 전송하세요. 제공자 접두사도, 라우팅 접미사도 필요 없습니다. hiapi는 이 모델에 대해 중복성 제공을 위해 두 개의 백엔드 라우트(default 및 aws)를 나열하지만 둘은 동일한 모델 ID를 공유합니다. 둘 중에서 선택할 필요가 없습니다.

요청 형식이 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-opus-4-8",
    "messages": [{"role": "user", "content": "Count 1 to 3"}],
    "stream": true,
    "max_tokens": 20
  }'

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

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

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

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

data: [DONE]

청크에 걸쳐 choices[0].delta.content를 누적하여 전체 텍스트를 재구성하세요. 최종 데이터 이벤트(finish_reason 이후)는 delta가 아니라 usage 합계를 담고 있습니다.

도구 호출

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-opus-4-8",
    "messages": [{"role": "user", "content": "What is the status of task demo-123?"}],
    "max_tokens": 200,
    "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"와 함께 choices[0].message.tool_calls에 함수 이름 및 JSON 인코딩된 인자를 담아 반환됩니다. 로컬에서 함수를 실행한 다음, 결과를 일치하는 tool_call_id를 가진 role: "tool" 메시지로 다음 요청에 담아 보내세요. 그러면 모델이 이어서 진행합니다.

적응형 사고

Claude Opus 4.8은 선택적으로 활성화하는 추론 라운드를 지원합니다. "thinking": {"type": "adaptive"}를 추가하고 output_config.effort를 통해 노력 수준(low, medium, high 모두 확인됨)을 선택하세요:

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

이 기능을 기반으로 구축하기 전에 알아둘 점이 두 가지 있습니다. 첫째, "적응형"이란 모델이 프롬프트가 사고할 가치가 있는지 스스로 판단한다는 뜻입니다. low 또는 medium 노력 수준에서는 간단한 질문에 reasoning_details 필드가 전혀 반환되지 않을 수 있으므로 모든 요청이 이 필드를 생성한다고 가정하지 마세요. 둘째, hiapi의 다른 일부 텍스트 모델과 달리 Opus 4.8은 사람이 읽을 수 있는 추론 트레이스를 반환하지 않습니다. reasoning_details 배열의 reasoning.text 항목은 비어 있게 반환되며, signature 항목만 채워집니다. reasoning_details는 불투명한 이어가기 상태로 취급하세요. 세션을 후속 도구 호출로 이어갈 경우 그대로 전달하고, 파싱하거나 사용자에게 표시하지 마세요.

오류 처리

인증 실패는 HTTP 401과 hiapi_error 봉투를 반환합니다:

{
  "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-opus-4-8이 제가 보내야 하는 정확한 모델 ID인가요? 예. model 필드에 순수 문자열 claude-opus-4-8을 보내세요. 제공자별 접두사도, 라우팅 접미사도 필요 없습니다. hiapi가 내부적으로 올바른 백엔드 라우트로 해석합니다.

hiapi 이미지 및 비디오 모델과 동일한 /v1/tasks 흐름을 사용하나요? 아니요. Claude Opus 4.8과 같은 텍스트 모델은 동기식 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로 사용하세요. 기본 채팅, 스트리밍 또는 도구 호출에 다른 코드 변경은 필요 없습니다.

Opus 4.8과 Sonnet 4.6 중 무엇을 사용해야 하나요? Opus 4.8은 더 높은 역량과 더 높은 비용의 계층입니다. 더 어려운 추론, 코딩 또는 에이전트 작업에서 정확성이 지연 시간이나 토큰당 비용보다 중요할 때 선택하세요. 트래픽이 많거나 지연에 민감한 워크로드에서는 Claude Sonnet 4.6이 더 낮은 가격에 동일한 API 형태를 제공합니다.

thinking은 항상 가시적인 추론 트레이스를 반환하나요? 양쪽 모두 아닙니다. 적응형 사고는 간단하다고 판단한 요청에 대해 추론을 완전히 건너뛸 수 있으며, 실제로 사고할 때에도 Opus 4.8의 reasoning_details는 현재 텍스트 필드가 비어 있게 반환되고 signature만 채워집니다. 항상 읽을 수 있는 트레이스가 존재한다고 가정하는 UI를 구축하지 마세요.

대규모 배치를 실행하기 전에 현재 가격은 어디에서 확인하나요? odiapi의 가격 페이지에 Claude Opus 4.8의 실시간 토큰당 요금이 나열되어 있습니다. 예산을 세우기 전에 확인하세요. 이 문서에는 오래될 수 있는 숫자가 하드코딩되어 있지 않습니다.

태그채팅 완성 APIAPI 튜토리얼Anthropic

관련 글

모든 아티클 보기 →

영구 AI 아티팩트로 빌드 시작하기

API 키를 받아 태스크 기반의 하나의 API로 이미지, 비디오, 오디오 모델을 호출하세요.

API 문서 보기