튜토리얼

Claude Opus 5.5 API: 바로 실행 가능한 curl과 Python 빠른 시작

Sep 29, 2026

Claude Opus 5.5는 Anthropic의 최신 에이전트형 코딩 및 장문 컨텍스트 추론 모델이며, hiapi는 플랫폼에 출시된 당일에 연동을 완료했습니다. hiapi의 이미지, 비디오, 오디오 모델과 달리—그 모델들은 모두 비동기 POST /v1/tasks → 폴링 방식을 사용합니다—Claude Opus 5.5는 순수 텍스트 대화 모델이므로 /v1/chat/completions에 동기 요청 하나만 보내면 호출할 수 있습니다. 이 가이드는 바로 실행 가능한 curl 호출, 동일한 호출의 Python 버전, 그리고 출시 전에 알아야 할 프로덕션 세부 사항(추론 강도, 스트리밍 출력, 오류 처리)을 제공합니다.

준비 사항

hiapi 계정과 API 키가 필요합니다. API Keys 페이지에서 생성할 수 있습니다—Claude Opus 5.5를 포함한 모든 hiapi 모델은 동일한 키를 공유합니다.
SDK 설치가 필요하지 않습니다. Claude Opus 5.5는 hiapi의 OpenAI 호환 Chat Completions 형식을 사용하므로 어떤 HTTP 클라이언트(curl, requests, fetch)든 바로 사용할 수 있습니다.

최소 동작 요청(curl)

curl -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "messages": [
      { "role": "user", "content": "Give me three tips for reviewing a Python pull request." }
    ],
    "stream": false
  }'

모델 id를 그대로 전달하면 됩니다—라우팅 접미사도, 공급자 식별자 접두사도 필요하지 않습니다. 호출이 성공하면 표준 채팅 완성 객체가 반환됩니다:

{
  "id": "msg_...",
  "object": "chat.completion",
  "model": "claude-opus-5-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 42,
    "total_tokens": 55,
    "usage_semantic": "openai",
    "usage_source": "anthropic"
  }
}

답변은 choices[0].message.content에서 읽습니다—여기에는 폴링할 output[0].url도, 추적할 작업 id도 없습니다.

Python에서의 동일한 흐름

import requests

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "claude-opus-5-5",
        "messages": [
            {"role": "user", "content": "Give me three tips for reviewing a Python pull request."}
        ],
        "stream": False,
    },
)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])

이 엔드포인트는 OpenAI Chat Completions의 전송 형식을 사용하므로 동일한 요청 본문 구조를 어떤 언어의 어떤 HTTP 클라이언트에서도 그대로 사용할 수 있습니다—기본 URL과 Bearer 키 외에 hiapi에 특화된 것은 배울 필요가 없습니다.

추론 강도, 사고와 스트리밍 출력

Claude Opus 5.5의 확장 사고는 항상 켜져 있습니다—비활성화할 수도 없고, token 예산을 수동으로 지정할 수도 없습니다. 제어할 수 있는 것은 모델이 얼마나 추론할지이며, output_config.effort를 통해 설정합니다:

{
  "model": "claude-opus-5-5",
  "messages": [{ "role": "user", "content": "..." }],
  "output_config": { "effort": "medium" }
}

effort는 low, medium(필드를 생략할 때의 기본값), high, xhigh 또는 max를 받습니다—빠르고 저렴한 답변에서 점진적으로 심층적이고 신중한 답변으로 넘어갑니다. 응답의 message에는 모델의 내부 사고 궤적을 저장하는 reasoning_details 배열이 포함됩니다. 간단한 일회성 호출에서는 이를 무시하고 message.content만 읽어도 안전합니다.

긴 답변의 경우 전체 응답을 기다리지 않고 점진적 출력을 얻으려면 "stream": true를 설정하세요:

curl -N https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-opus-5-5","messages":[{"role":"user","content":"..."}],"stream":true}'

각 데이터 청크는 data: {...} 한 줄이며, 형식은 chat.completion.chunk이고 점진적 텍스트는 choices[0].delta.content에 있습니다. finish_reason이 비어 있지 않은 청크(보통 "stop")를 받을 때까지 계속 읽으세요—그것이 응답의 끝입니다.

Claude Opus 5.5는 도구/함수 호출도 지원하며, 100만 token 컨텍스트 윈도우와 최대 12.8만 token 출력을 갖추고 있어 대규모 코드베이스나 긴 문서 작업에 적합하고, 짧은 질의응답에만 국한되지 않습니다.

프로덕션 주의 사항

인증 오류는 400이 아닌 401을 반환합니다. 키가 없거나 유효하지 않으면 다음이 반환됩니다:
```
{ "error": { "code": "permission_denied", "message": "This API key is invalid...", "type": "hiapi_error", "request_id": "..." } }
```
HTTP 401을 별도로 확인하고, 지원팀에 문의해야 할 때는 request_id를 제공하세요—이 오류의 다른 원인에 대해서는 전체 유효하지 않은 API 키 문제 해결 가이드를 참고하세요.
여기에는 콜백/Webhook 옵션이 없습니다. 해당 방식은 hiapi의 비동기 작업 기반 모델(이미지, 비디오, 오디오)에 적용됩니다. Chat Completions는 요청/응답만 지원하므로 stream: true가 단일 블로킹 호출 외의 유일한 선택지입니다.
이 호출은 본질적으로 멱등합니다—작업 id가 실수로 중복 생성될 일이 없으므로 동일한 프롬프트를 다시 실행해도 괜찮다면 타임아웃 재시도가 안전합니다.
속도 제한에 주의하세요, 특히 고동시성 워크로드에서 주의해야 합니다. 백오프 전략은 429 속도 제한 오류 처리 방법을 참고하세요.
Token 가격(입력, 출력, 캐시 token이 각각 과금됨)은 Claude Opus 5.5 모델 페이지와 가격 페이지에 지속적으로 업데이트됩니다—청구 로직에 숫자를 하드코딩하지 말고 해당 페이지에서 읽어오세요.

더 읽어보기

Claude Opus 5.5 모델 페이지—전체 사양 표와 실시간 가격
Claude Sonnet 4.6 API 가이드—동일한 Chat Completions 형식에서 더 가볍고 빠른 Claude 선택지
Python으로 OpenAI 호환 프록시 구축하기—여러 채팅 모델을 단일 내부 API 뒤에서 프록시하려는 경우 유용합니다
API 키 관리하기

자주 묻는 질문

Claude Opus 5.5 API는 스트리밍 출력을 지원하나요? 지원합니다—"stream": true를 설정하고 위에서 설명한 대로 data: {...} 청크를 읽으세요.

프로덕션 환경에서 Claude Opus 5.5를 호출하려면 API 키가 필요한가요? 필요합니다. 모든 요청에는 Authorization: Bearer sk-<your key>가 포함되어야 하며, 프로덕션 API는 키 없는 또는 익명 액세스를 제공하지 않습니다.

token을 절약하기 위해 Claude Opus 5.5의 사고를 끌 수 있나요? 불가능합니다. 이 모델의 사고는 항상 켜져 있으며, 유일하게 제어할 수 있는 것은 output_config.effort 수준(low에서 max까지)으로, 속도/비용과 깊이 사이에서 균형을 잡습니다.

Claude Opus 5.5는 hiapi의 이미지 모델처럼 /v1/tasks를 통해 호출되나요? 아닙니다. hiapi의 이미지, 비디오, 오디오 모델만 비동기 작업 및 폴링 방식을 사용합니다. Claude Opus 5.5는 텍스트 모델로 /v1/chat/completions를 사용하며, 동일한 응답에서 답변을 반환합니다.

컨텍스트 윈도우와 최대 출력 길이는 얼마인가요? 100만 token 컨텍스트, 최대 12.8만 token 출력—전체 저장소나 긴 문서 프롬프트를 처리하기에 충분합니다.

Claude Opus 5.5는 도구/함수 호출을 지원하나요? 지원합니다. 스트리밍 출력과 OpenAI 호환 메시지 형식도 함께 지원합니다.