튜토리얼
HiAPI API로 gpt-6-sol 사용하는 방법: curl, Python 그리고 한 번에 성공하는 요청
이 페이지에서
첫 호출 전에 준비해야 할 것
코드를 작성하기 전에 세 가지를 먼저 준비하세요. 이 튜토리얼의 나머지 내용은 모두 이를 기반으로 합니다.
HiAPI API 키
HiAPI API로 보내는 모든 요청은 API 키로 인증해야 합니다. HiAPI 계정 대시보드에서 키를 만들고 안전한 곳에 보관하세요. 가능하면 소스 코드 파일이 아니라 환경 변수에 두는 것이 좋습니다. 비밀번호처럼 다루세요. 유출되면 즉시 교체하세요.
export HIAPI_API_KEY="your-api-key-here"
기본 엔드포인트
이 가이드의 모든 호출은 HiAPI API의 기본 엔드포인트로 전송되며, 모든 모델은 동일한 요청 경로 형식으로 접근합니다. 모델마다 별도의 호스트나 SDK를 준비할 필요가 없습니다. gpt-6-sol은 클라이언트 설정을 바꾸는 것이 아니라 요청 본문에서 선택합니다.
HTTP 클라이언트
다음 중 하나가 필요합니다:
curl. 대부분의 Linux 및 macOS 시스템과 Windows 터미널에서 기본으로 사용할 수 있습니다.requests라이브러리가 설치된 Python(pip install requests), 또는 의존성을 추가하고 싶지 않다면 표준 라이브러리urllib.
다른 도구는 필요 없습니다. 특정 공급업체의 SDK도, 모델과 관련된 것을 설치할 필요도 없습니다. JSON 요청 본문과 헤더를 포함한 HTTPS POST 요청을 보낼 수 있으면 gpt-6-sol을 호출할 수 있습니다.
지금부터 들일 만한 습관이 하나 있습니다. 사용 중인 정상 동작 요청을 초안 파일에 기록해 두세요. 실패가 발생했을 때 실패한 호출을 마지막으로 알려진 정상 호출과 비교할 수 있습니다.
bearer 키로 인증하기
인증은 첫 호출에서 가장 실수가 잦은 부분이므로 신중하게 다룰 가치가 있습니다.
Authorization 헤더
HiAPI API는 키가 표준 bearer 헤더에 있기를 기대합니다:
Authorization: Bearer $HIAPI_API_KEY
문자 그대로 Bearer라는 단어, 공백 하나, 그다음 키입니다. 흔한 실수로는 Bearer 단어를 빠뜨리거나, 값을 복사할 때 불필요한 줄바꿈이 들어가거나, 클라이언트가 이미 따옴표를 추가한 상태에서 키에 또 따옴표를 붙이는 경우가 있습니다.
콘텐츠 유형은 JSON이어야 함
요청은 JSON 본문을 담으므로 콘텐츠 유형 헤더가 일치해야 합니다:
Content-Type: application/json
이 헤더가 없어도 일부 서버는 본문을 파싱하지만, 그것에 의존해서는 안 됩니다. 명시적으로 설정하세요. 콘텐츠 유형 불일치는 요청 검증 오류의 흔한 원인이며, 이런 오류는 본문 오류처럼 보입니다.
최소 헤더 집합
위의 두 헤더만 있으면 됩니다:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
헤더 집합은 가능한 한 작게 유지하세요. 다른 API 예제에서 가져온 추측성 헤더는 도움이 되기보다 혼란을 일으킬 가능성이 더 큽니다. 이 두 헤더를 사용한 호출이 성공하면, 이후 비교에 사용할 깨끗한 기준선이 생깁니다.
키를 셸 기록이나 커밋된 파일에 직접 붙여넣지 마세요. 위처럼 환경 변수를 참조하면 키를 소스 코드와 터미널 기록에서 멀리 둘 수 있습니다.
gpt-6-sol용 요청 본문 구성하기
요청 본문은 JSON이며, 핵심은 메시지 목록입니다. 최소 구성으로 시작하고, 호출이 성공한 뒤에만 필드를 추가하세요.
최소 요청 페이로드
최소한의 유용한 요청 본문은 모델을 지정하고 메시지 하나를 제공합니다:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "API bearer token이 무엇인지 한 문장으로 설명해 주세요." }
]
}
여기서 두 필드가 역할을 합니다:
model은gpt-6-sol을 선택하므로, 같은 엔드포인트가 이후 다른 모델도 제공할 수 있습니다.messages는 순서대로 나열된 대화 턴 목록입니다. 각 항목에는role(system,user,assistant)과content문자열이 있습니다.
안전한 기본값과 선택적 추가 항목
model과 messages를 필수로 간주하세요. 나머지는 모두 선택 사항이며 의식적으로 추가해야 합니다:
messages맨 앞에 두는system메시지는 대화의 행동이나 어조를 설정합니다. 이것은 별도의 최상위 필드가 아니라 일반 메시지입니다.- 필요하면 출력 길이 제어를 요청 본문의 매개변수로 설정합니다. 기본 출력이 사용 사례에 비해 너무 짧거나 너무 길 때만 추가하세요.
- 샘플링 관련 매개변수는 유효성이 아니라 출력 형태를 바꿉니다. 실패한 호출을 디버깅할 때는 이를 변경하지 마세요. 인증이나 요청 본문 구조 오류를 고칠 수 없습니다.
실용적인 규칙 하나
실패가 발생하면 요청 페이로드는 최소 예제에 최대한 가깝게 유지하세요. 선택적 필드를 하나씩 제거해 호출이 성공할 때까지 줄인 다음, 다시 추가하세요. 이렇게 하면 문제를 빠르게 격리할 수 있습니다. 나쁜 매개변수 하나가 좋은 매개변수 다섯 개 속에 묻힌 나쁜 매개변수보다 찾기 쉽습니다.
curl로 한 번에 성공하는 요청 보내기
아래는 키를 내보낸 상태라면 바로 실행할 수 있는 전체 명령입니다. 위에서 설명한 HiAPI API 규칙에 맞는 자리표시자 엔드포인트 경로를 사용합니다.
curl -sS -X POST "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "API bearer token이 무엇인지 한 문장으로 설명해 주세요." }
]
}'
HIAPI_BASE_URL을 HiAPI 대시보드의 기본 엔드포인트로 설정하세요. 이 플래그들이 중요합니다:
-X POST는 메서드를 설정합니다. 이 호출은 모두 POST입니다.-H는 각 헤더를 한 줄에 하나씩 추가합니다.-d는 JSON 요청 본문을 제공합니다. 작은따옴표는 셸 보간을 막습니다.-sS는 출력을 조용하게 유지하지만 오류는 표시합니다. 스크립트 작성 시 필요한 동작입니다.
응답 읽기
성공한 응답은 JSON입니다. 일반적으로 모델 이름과 choices 목록을 포함한 최상위 객체가 보이며, 각 choice에는 메시지가 있고 그 content에 생성된 텍스트가 저장됩니다. 본문을 읽기 전에 구조를 먼저 읽으세요. 객체가 파싱되는지 확인한 다음 content 필드를 찾으세요.
가독성을 높이려면 JSON 포맷 도구로 파이프하세요:
... | python -m json.tool
터미널에 오류 객체가 출력되었다면 호출이 성공하지 않은 것입니다. 프롬프트를 조정하지 말고 오류 섹션으로 넘어가세요. 요청이 모델에 도달조차 하지 않았다면 문제는 프롬프트에 있지 않습니다.
Python으로 같은 요청 보내기
방금 curl로 검증한 요청 페이로드는 그대로 옮길 수 있습니다. 요청 본문을 완전히 동일하게 유지하세요. 그래야 터미널에서 검증한 수정 사항이 코드에도 적용됩니다.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-6-sol",
"messages": [
{"role": "user", "content": "API bearer token이 무엇인지 한 문장으로 설명해 주세요."}
],
}
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
}
response = requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
data = response.json()
for choice in data.get("choices", []):
message = choice.get("message", {})
print(message.get("content", ""))
이 버전이 애플리케이션 코드에서 더 안전한 이유
- 요청 본문은 딕셔너리입니다.
json=payload를 전달하면requests가 이를 직렬화하고 콘텐츠 유형을 대신 설정하지만, 헤더를 명시적으로 유지하면 클라이언트를 바꿀 때 예상치 못한 문제를 피할 수 있습니다. - 키는 환경 변수에서 가져옵니다. 비밀이 하드코딩되지 않으므로 이 파일은 커밋할 수 있습니다.
raise_for_status()가 먼저 실행됩니다. 2xx가 아닌 응답은 예외를 즉시 발생시켜, 오류 응답 본문에 존재하지 않는 필드를 읽으려 하기 전에 멈춥니다.- 타임아웃이 설정됩니다. 타임아웃이 없으면 정체된 연결이 작업 프로세스를 무기한 매달리게 할 수 있습니다.
choices를 순회하는 루프는 키 누락도 방지하므로, 예제가 출력이 거의 없거나 전혀 없는 응답도 견딜 수 있습니다. 이 골격을 중심으로 프로덕션 래퍼를 만드세요. 검증하고, 전송하고, 상태를 확인한 다음 파싱하세요.
기다리지 않고 응답 스트리밍으로 받기
기본적으로 API는 전체 답변을 단일 JSON 응답으로 반환합니다. 긴 출력이나 대화형 인터페이스에서는 응답이 생성되는 동안 점진적으로 전달되도록 요청할 수 있습니다.
스트리밍 스위치
스트리밍은 다른 엔드포인트가 아니라 요청 본문 플래그로 활성화합니다:
{
"model": "gpt-6-sol",
"messages": [
{ "role": "user", "content": "HTTP 상태 코드에 관한 짧은 글을 써 주세요." }
],
"stream": true
}
비스트리밍 호출이 이미 동작한 뒤에 이 플래그를 마지막으로 추가하세요. 이것은 요청의 유효성이 아니라 응답의 구성 방식을 바꿉니다.
증분 출력 소비하기
스트리밍을 켜면 응답은 더 이상 단일 JSON 문서가 아닙니다. 보통 줄 단위로 구분된 일련의 이벤트로 도착하며, 각 이벤트는 출력의 작은 조각을 담습니다. 클라이언트는 전체 응답 본문에 .json()을 호출하는 대신, 도착하는 즉시 읽어야 합니다.
with requests.post(
f"{base_url}/chat/completions",
headers=headers,
json=payload,
stream=True,
timeout=60,
) as response:
response.raise_for_status()
for line in response.iter_lines():
if line:
print(line.decode("utf-8"))
터미널에서 같은 스위치는 비스트리밍 호출과 다르게 동작합니다. 출력이 점진적으로 나타나므로, 잘린 파이프는 실제로는 스트림이 중단된 것일 뿐 실패한 요청처럼 보일 수 있습니다.
어느 것을 사용할까
배치 작업, 테스트, 그리고 완전한 객체를 한 번에 받아야 하는 모든 경우에는 비스트리밍을 사용하세요. 누군가 텍스트를 기다리고 있거나 출력이 길어 지연이 눈에 띌 때는 스트리밍을 사용하세요. 코드베이스에 두 경로를 모두 유지하세요. 비스트리밍 경로가 디버깅하기 더 쉽습니다.
흔한 오류 코드 읽고 고치기
먼저 상태 코드로, 다음으로 응답 본문으로 진단하세요. 어느 계층이 실패했는지 확인하기 전에 모델을 바꾸거나 프롬프트를 다시 쓰지 마세요.
401 Unauthorized
원인: 키가 없거나, 형식이 잘못되었거나, 폐기되었습니다. 수정: 헤더가 정확히 Authorization: Bearer <key>로 작성되었는지 확인하고, 숨은 공백 문자나 만료된 환경 변수가 있는지 점검하며, 대시보드에서 키가 여전히 유효한지 확인하세요. 빈 변수 오류를 잡으려면 값이 아니라 변수의 길이를 출력하세요.
400 Bad Request
원인: 요청 본문을 파싱할 수 없거나 필수 필드가 누락되었습니다. 수정: model과 messages만 포함한 최소 요청 페이로드를 다시 보내세요. 보내기 전에 python -m json.tool로 JSON을 검증하세요. 후행 쉼표나 model의 오타가 흔한 원인입니다. Content-Type이 application/json인지 확인하세요.
403 Forbidden
원인: 키는 유효하지만 요청한 리소스에 대한 접근 권한이 없습니다. 수정: 계정에 gpt-6-sol 접근 권한이 있는지, 요청 본문의 모델 이름이 계정에 구성된 것과 일치하는지 확인하세요.
404 Not Found
원인: URL 경로가 잘못되었습니다. 보통 엔드포인트 오타이거나 기본 경로가 빠졌거나 중복된 경우입니다. 수정: 전체 URL을 동작하는 curl 호출과 문자 단위로 비교하세요.
429 Too Many Requests
원인: 계정이 허용하는 범위보다 빠르게 요청을 보냈습니다. 수정: 백오프하고 지연을 늘려 재시도하세요. 응답 헤더의 재시도 안내를 따르고, 루프에서 촘촘히 재시도하지 마세요. 문제가 악화될 뿐입니다. 이것을 5xx와 구분하세요. 5xx는 요청 속도 문제가 아니라 서버 측 문제입니다.
5xx 서버 오류
원인: 서비스가 원래 유효한 요청을 처리하지 못했습니다. 수정: 백오프하며 재시도하세요. 문제가 지속되면 응답 본문과 요청 ID를 캡처하고, 이미 동작하는 요청 페이로드는 변경하지 마세요.
반복 가능한 디버깅 순서
- 상태 코드 — 인증, 경로, 요청 본문 중 어느 문제인가?
- 응답 본문 — 문제가 있는 필드를 지목하는가?
- 요청 페이로드 구조 — 최소 예제로 돌아가기.
- 프롬프트나 매개변수는 마지막에 고려.
이 순서는 실패에서 수정까지 걸리는 시간을 꾸준히 줄여 줍니다. 호출이 안정되면 동작하는 curl과 Python 버전을 나란히 유지하세요. 그러면 앞으로의 모든 테스트가 알려진 정상 상태에서 시작합니다.