튜토리얼
HiAPI API로 claude-opus-5-5@aws를 호출하는 방법: curl 및 Python 가이드
이 페이지에서
HiAPI를 통해 claude-opus-5-5@aws를 사용하는 모습
HiAPI는 여러 모델에 통일된 HTTP 인터페이스를 제공합니다. 제공자마다 별도로 계정, SDK, 자격 증명 저장소를 구성할 필요 없이, HiAPI를 향해 동일한 요청 형식을 사용하고 모델 식별자로 원하는 모델을 선택하면 됩니다. 이 튜토리얼에서 해당 식별자는 claude-opus-5-5@aws입니다——@aws 접미사는 모델 이름의 일부이며 독립된 필드가 아니므로 그대로 전달해야 합니다.
한 번의 요청 수명 주기는 다음과 같습니다:
- 인증——
Authorization요청 헤더에 bearer token 형태로 HiAPI API 키를 전송합니다. - 채팅식 페이로드 전송——
model과messages배열을 포함한 JSON 요청 본문으로, 각 메시지는role(system,user,assistant)과content를 가집니다. - JSON 응답 수신——어시스턴트의 응답은 응답의
choices배열에 나타나며, 사용량 메타데이터가 함께 포함됩니다. - 대화 계속——어시스턴트 메시지와 다음 사용자 메시지를 동일한
messages배열에 추가하고 다시 전송합니다. 이 API는 무상태(stateless)이며, 전체 대화는 요청 페이로드에 보관됩니다.
모든 모델의 요청 구조가 동일하므로, claude-opus-5-5@aws를 위해 작성한 코드는 model 문자열만 변경하면 다른 모델로 이전할 수 있습니다. 이 필드는 여러 파일에 하드코딩하지 말고 코드의 한 곳——설정 값이나 환경 변수——에 집중시키세요.
이름에 관한 참고 사항: 플랫폼은 이 모델을 claude-opus-5-5@aws로 문서화합니다. 이 정확한 문자열을 사용하세요. 오타, 불필요한 공백, 접미사 누락은 유용한 경고 없이 모델을 찾을 수 없음 오류를 발생시킵니다.
자격 증명 발급 및 인증 완료
API를 호출하기 전에 HiAPI 계정에서 API 키를 발급받아야 합니다. 키는 기밀로 취급하세요: 환경 변수나 플랫폼의 시크릿 관리자에 저장하고, 절대 소스 관리에 넣거나 브라우저로 전송되는 클라이언트 코드에 넣지 마세요.
HiAPI는 Authorization 요청 헤더의 bearer token으로 요청을 인증합니다:
export HIAPI_API_KEY="your-api-key-here"
모든 요청에는 다음이 포함되어야 합니다:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
대부분의 인증 실패를 피하는 몇 가지 실용 규칙:
- 리터럴
Bearer접두사를 유지하고, 그 뒤에 공백 하나, 그 다음 키를 둡니다. 접두사나 공백이 빠지는 것은 흔한 복사-붙여넣기 실수입니다. - 요청 헤더 값에서 키를 따옴표로 감싸지 마세요.
- 키를 교체하면 환경 변수를 업데이트하고 프로세스를 재시작하세요——오래 실행되는 워커가 종종 이전 값을 캐시합니다.
- 키를
.env파일에 붙여넣을 때 후행 공백이나 줄바꿈을 확인하세요; 일부 로더는 자동으로 제거하지 않습니다.
키가 없거나 형식이 잘못된 경우 인증 오류(401 계열)를 받게 되며 모델 오류가 아니므로, 이후 문제와 쉽게 구분할 수 있습니다. 요청이 인증을 통과하면 동일한 헤더를 스트리밍, 도구 호출 및 이 가이드의 다른 모든 패턴에 사용할 수 있습니다——기능마다 별도의 자격 증명을 사용할 필요가 없습니다.
서버 측 코드의 경우, 시작 시 키를 한 번 로드하여 공유 클라이언트나 작은 래퍼 함수에 전달하세요. 이렇게 하면 기밀을 한 곳에 집중시키고 개발 자격 증명과 프로덕션 자격 증명 간 전환이 쉬워집니다.
curl로 실행 가능한 요청 구성하기
다음은 완전하고 실행 가능한 요청입니다. 자리 표시자 키를 자신의 키로 바꾸거나, 먼저 이전 섹션의 export를 실행하여 셸이 대체하도록 하세요.
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-5-5@aws",
"messages": [
{
"role": "user",
"content": "멱등 POST 엔드포인트가 결제 API에 왜 중요한지 세 문장으로 설명해 주세요."
}
]
}'
항목별 분해:
- 엔드포인트——
POST https://api.hiapi.ai/v1/chat/completions. - 요청 헤더——bearer token과 JSON 콘텐츠 타입. 둘 다 필수입니다.
model——정확한 식별자claude-opus-5-5@aws.messages——role과 content 객체로 구성된 배열. 마지막 사용자 메시지가 모델이 응답할 내용입니다.- 페이로드——
-d는 원시 JSON을 전송하므로 따옴표 처리가 중요합니다. 셸에서 전체 요청 본문을 작은따옴표로 감싸고, JSON 키에는 큰따옴표를 사용하세요.
응답은 choices 배열을 포함한 JSON입니다. 생성된 텍스트는 choices[0].message.content에 있으며, 소비량을 모니터링할 수 있도록 사용량 정보(토큰 수)가 포함됩니다. 응답 사용량은 토큰 기준으로 과금되며, 현재 요금은 웹사이트의 가격 패널에서 확인할 수 있습니다.
일반적인 조정:
{
"model": "claude-opus-5-5@aws",
"max_tokens": 512,
"temperature": 0.2,
"messages": [
{"role": "system", "content": "당신은 간결한 기술 편집자입니다."},
{"role": "user", "content": "위의 요청 본문을 한 줄로 요약해 주세요."}
]
}
max_tokens로 통제 불능의 생성을 제한하고, temperature로 장황함과 분산을 제어하며, system 메시지로 각 대화의 행동을 한 번 설정하세요. system 메시지는 동일한 messages 배열에서 사용자 턴 앞에 위치해야 합니다.
Python에서의 동일한 요청
Python 버전은 표준 라이브러리의 urllib를 사용하므로 이 코드 조각은 아무것도 설치하지 않고 실행할 수 있습니다. 클라이언트 라이브러리를 선호한다면 요청 구조는 완전히 동일합니다——전송 방식만 다릅니다.
import json
import os
import urllib.request
API_URL = "https://api.hiapi.ai/v1/chat/completions"
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "claude-opus-5-5@aws"
def ask(user_message: str, system_message: str | None = None) -> str:
messages = []
if system_message:
messages.append({"role": "system", "content": system_message})
messages.append({"role": "user", "content": user_message})
payload = json.dumps({
"model": MODEL,
"messages": messages,
}).encode("utf-8")
request = urllib.request.Request(
API_URL,
data=payload,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
method="POST",
)
with urllib.request.urlopen(request) as response:
body = json.loads(response.read().decode("utf-8"))
return body["choices"][0]["message"]["content"]
if __name__ == "__main__":
print(ask("정확히 다섯 단어로 인사해 주세요."))
이 구조를 유지할 가치가 있는 이유:
MODEL과API_URL은 모듈 수준 상수이므로 모델이나 엔드포인트 전환은 한 줄 변경으로 끝납니다.- 키는 환경에서 가져오며, 함수는 원시 기밀 매개변수를 절대 받지 않습니다.
- 파싱 로직이 끝에 격리되어 있으므로
urllib을httpx나requests로 바꿔도 대화 구성 방식을 수정할 필요가 없습니다.
다중 턴 대화를 계속하려면 다시 전송하기 전에 어시스턴트의 응답과 다음 사용자 메시지를 messages에 추가하세요. 배열이 컨텍스트 한도에 도달할 때까지 계속 키우다가, 이전 턴을 하나의 system 메시지로 요약하여 예산 내에 유지하세요. 응답의 사용량은 토큰 기준이며, 현재 요금은 웹사이트의 가격 패널에 나열되어 있습니다.
상호작용 시나리오를 위한 스트리밍 응답
채팅 UI와 장시간 생성의 경우, 스트리밍은 전체 응답을 기다리지 않고 출력이 생성되는 즉시 부분 콘텐츠를 전송합니다. 요청 본문은 한 필드를 제외하고 동일합니다:
{
"model": "claude-opus-5-5@aws",
"messages": [{"role": "user", "content": "방금 스트리밍을 도입한 라이브러리를 위한 짧은 변경 로그를 작성해 주세요."}],
"stream": true
}
stream: true일 때, 엔드포인트는 서버 전송 이벤트(server-sent events)로 응답합니다: 각 청크는 data: 접두사가 붙은 한 줄이며, 스트림은 최종 종료 표시 줄로 끝납니다. 대부분의 청크는 전체 메시지가 아닌 텍스트 조각을 가진 delta를 choices 배열에 포함합니다.
curl 사용 시, -sS의 조용한 효과를 제거하여 출력이 점진적으로 도착하는 것을 관찰하세요:
curl -N https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-opus-5-5@aws","stream":true,"messages":[{"role":"user","content":"천천히 다섯까지 세어 주세요."}]}'
-N 플래그는 버퍼링을 비활성화하여 청크가 도착하는 대로 볼 수 있게 합니다. Python에서는 응답을 줄 단위로 읽습니다:
with urllib.request.urlopen(request) as response:
for raw_line in response:
line = raw_line.decode("utf-8").strip()
if not line.startswith("data: "):
continue
data = line[len("data: "):]
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
print(text, end="", flush=True)
실용 팁:
- 항상
[DONE]종료 표시와 빈 줄/연결 유지 줄을 처리하세요; 모든 줄이 JSON이라고 가정하지 마세요. - UI 스레드가 전체 스트림에서 차단되게 하지 마세요——delta가 도착하는 대로 버퍼에 추가하세요.
- 클라이언트 연결이 끊기면 응답을 닫아 업스트림 생성을 해제하세요.
- 스트리밍은 사용량 계산 방식을 바꾸지 않습니다; 마지막 청크가 일반적으로 사용량 메타데이터를 전달합니다. 과금은 출력 토큰 기준이며, 현재 요금은 웹사이트의 가격 패널에서 확인할 수 있습니다.
대화에 도구 호출 추가하기
도구 사용은 모델이 텍스트 생성만이 아니라 코드에서 구조화된 작업을 요청할 수 있게 합니다. 요청에는 tools 배열이 추가되고; 대화에는 tool_calls를 담은 어시스턴트 메시지와 결과를 담은 role: "tool" 메시지가 추가됩니다.
JSON Schema로 도구의 매개변수를 정의하세요:
{
"model": "claude-opus-5-5@aws",
"messages": [
{"role": "user", "content": "리스본의 현재 날씨는 어때요?"}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "도시의 현재 날씨를 반환합니다.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "도시 이름, 예: Lisbon"}
},
"required": ["city"]
}
}
}
]
}
모델은 최종 텍스트가 아닌 tool_calls를 포함한 메시지를 반환할 수 있습니다. 각 항목은 함수 이름을 지정하고 JSON 문자열 형태의 인수를 전달합니다. 당신의 역할은 자신의 시스템에 대해 해당 함수를 실행한 후 결과를 추가하는 것입니다:
tool_calls를 포함한 어시스턴트 메시지를 그대로messages에 추가합니다.- 각 호출에 대해
role: "tool", 어시스턴트 메시지에서 일치하는tool_call_id, 그리고 직렬화된 결과로 설정된content를 포함한 메시지를 추가합니다. - 동일한
tools배열을 사용하여 요청을 다시 전송합니다. 모델은 이후 당신의 결과를 바탕으로 자연어 답변을 생성합니다.
일찍 확립할 가치가 있는 보호 조치:
- 매개변수 검증——어떤 작업을 수행하기 전에 schema에 따라 매개변수를 검증하세요——모델 출력을 셸이나 데이터베이스 쿼리에 직접 전달하지 마세요.
- 루프 제한. 도구 호출 턴 수에 상한(보통 3~5회)을 설정하여 지속적으로 호출을 요청하는 모델이 무한 루프에 빠지지 않도록 하세요.
- 오류를 도구 결과로 반환. 함수가 실패하면 일치하는
tool_call_id와 함께 짧은 오류 문자열을 전송하세요; 모델은 이후 재시도하거나 실패 이유를 설명할 수 있으며 멈추지 않습니다. - 도구 설명을 정확하게 유지. 모호한 설명은 매개변수 오류보다 훨씬 자주 도구 선택 오류를 유발합니다.
도구 정의는 요청과 함께 평가되며 토큰 사용량에 포함됩니다. 현재 요금은 웹사이트의 가격 패널에 게시되어 있습니다.
다음 단계
최소한의 curl 호출로 시작하여 Python 래퍼 함수로 옮기고, 그런 다음 사용 사례에 필요할 때만 스트리밍과 도구를 추가하세요. 모델 문자열 claude-opus-5-5@aws는 항상 동일합니다——나머지는 모두 요청 페이로드의 필드입니다.