블로그

튜토리얼

HiAPI API로 gpt-5.6-sol@azure를 호출하는 방법: curl과 Python

인증, 요청 본문 구조, 사용 가능한 예시 및 오류 처리

Nov 10, 2026
크림색과 흑연색의 여러 겹 종이 시트가 얕은 계단처럼 뒤로 물러나고, 테라코타색 시트 하나가 포인트로 더해진 모습 — gpt-5.6-sol@azure 튜토리얼의 표지 아트.
이 페이지에서

gpt-5.6-sol@azure가 HiAPI 모델 대상이라는 것의 의미

gpt-5.6-sol@azure는 모델 식별자이며, 독립된 SDK도, 독립된 엔드포인트도, 독립된 인증 방식도 아닙니다. 이것은 HiAPI로 보내는 채팅 완성 요청의 model 필드에 넣는 정확한 문자열입니다.

@azure 접미사는 해당 모델 변형이 어떤 백엔드 제공자가 서비스하는지를 알려줍니다. 애플리케이션 관점에서는 호출 방식이 전혀 달라지지 않습니다: 동일한 기본 URL, 동일한 bearer 인증, 동일한 요청 및 응답 구조로, 플랫폼의 다른 어떤 채팅 모델과도 같습니다. 추가로 설치할 것도 없고, 특정 제공자의 자격 증명도 필요 없습니다 — HiAPI가 자기 쪽에서 라우팅과 제공자 관계를 처리합니다.

실질적인 결과는 이렇습니다: 이미 사용 중인 OpenAI 호환 클라이언트라면 두 군데만 수정해 이 모델을 가리킬 수 있습니다. 클라이언트의 기본 URL을 HiAPI로 바꾸고, 모델 이름을 gpt-5.6-sol@azure로 설정하면 됩니다. 설정 어딘가에 모델 이름을 하드코딩해 두었다면, 플랫폼에서 모델을 전환할 때 바꿔야 할 것은 그 설정 값 하나뿐입니다 — 덕분에 A/B 비교가 매우 저렴해집니다.

이 튜토리얼에서 해당 식별자는 항상 리터럴 문자열 gpt-5.6-sol@azure로 등장합니다. 정확히 입력하세요. 대소문자를 구분하며, 복사-붙여넣기로 끼어든 불필요한 공백은 뒤에서 설명할 "알 수 없는 모델" 오류의 실제 원인 중 하나입니다.

시작하기 전에 필요한 것

  • 플랫폼에 접근할 수 있는 HiAPI 계정.
  • 계정에서 발급한 API 키.
  • curl이 설치된 셸, 또는 requests 라이브러리가 설치된 Python 3.

아래 예시에는 다른 도구가 전혀 필요하지 않습니다.

API 키 발급 및 인증 구성

HiAPI의 인증은 bearer 토큰 방식입니다. API 키를 Bearer라는 단어와 공백 하나를 앞에 붙여 모든 요청의 Authorization 헤더에 넣습니다.

Authorization: Bearer YOUR_API_KEY

키는 계정 대시보드에서 발급합니다. 비밀번호처럼 다루세요 — 잔액을 소모할 수 있는 살아있는 자격 증명이며, 커밋 기록, 스크린샷, 공유 노트북, 로그 라인에 절대 나타나서는 안 됩니다.

환경 변수에 저장하기

기본 방법은 셸 세션마다 한 번 키를 export하고, 나머지는 모두 환경에서 읽는 것입니다:

export HIAPI_API_KEY="your-key-here"

서버에서는 체크인된 .env 파일 대신 프로세스 관리자나 시크릿 저장소를 통해 설정하세요. .env 파일이 정말 유일한 선택지라면, 첫 키를 쓰기 전에 .gitignore에 추가하세요.

인라인 대신 참조하기

curl에서는 셸 변수를 참조하여 키가 명령 기록이나 프로세스 목록에 절대 나타나지 않게 하세요:

curl -H "Authorization: Bearer $HIAPI_API_KEY" ...

Python에서는 런타임에 os.environ으로 읽습니다:

import os

API_KEY = os.environ["HIAPI_API_KEY"]

일부러 os.environ.get("...") 대신 os.environ["..."]를 사용합니다. 변수가 없으면 열다섯 줄 뒤에 혼란스러운 인증 오류를 만나는 대신 시작 시점에 크게 실패하기를 원하기 때문입니다.

지금부터 체화해야 할 키 위생 규칙

  • 환경마다 키 하나. 개발 키와 프로덕션 키를 분리하면 한쪽을 깨뜨리지 않고 다른 쪽을 교체하거나 폐기할 수 있습니다.
  • 노출되면 교체. 키가 공개된 곳에 나타났다면 폐기하고 새로 발급하세요 — 커밋을 삭제하는 것만으로는 부족합니다.
  • 헤더를 로그로 남기지 마세요. 모든 헤더를 덤프하는 요청 로깅 미들웨어는 bearer 토큰을 디스크에 기꺼이 기록합니다. 로깅 전에 Authorization을 마스킹하세요.

첫 호출에서 인증 오류가 발생한다면 원인은 거의 항상 다음 중 하나입니다: 요청을 실행하는 셸과 다른 셸에서 변수를 export했거나, Bearer 접두사를 빠뜨렸거나, 키를 복사할 때 후행 개행 문자가 붙었거나.

최소 요청 본문의 구조 해부

gpt-5.6-sol@azure 호출은 모두 JSON 본문을 가진 POST입니다. 필드 하나만으로도 유효한 요청을 만들 수 있으며, 이것이 시작하기 가장 좋은 방법입니다: 먼저 응답을 받고, 그다음에 조절 값을 추가하세요.

필수 필드

  • model — 문자열 gpt-5.6-sol@azure. 요청을 올바른 대상으로 라우팅합니다.
  • messages — 메시지 객체 배열. 각 객체에는 role과 content가 있습니다. 관례적인 역할은 system(동작을 형성하는 지시), user(입력), assistant(다중 턴 대화의 이전 턴)입니다.

최소 요청 본문은 다음과 같습니다:

{
  "model": "gpt-5.6-sol@azure",
  "messages": [
    { "role": "user", "content": "Explain what an idempotency key is in one paragraph." }
  ]
}

이것으로 충분합니다. 응답은 채팅 완성 구조로 돌아옵니다: 첫 번째 요소가 message.content 아래에 어시스턴트 응답을 담고 있는 choices 배열과, 토큰 소비를 설명하는 usage 블록이 함께 옵니다. 코드는 다른 필드를 가정하지 말고 choices[0].message.content에서 읽어야 합니다.

알아 둘 만한 선택 필드

필수는 아니지만 가장 먼저 쓰게 될 것들입니다:

  • temperature — 샘플링 무작위성. 낮은 값은 출력을 더 결정적이고 반복적으로 만들고, 높은 값은 더 다양하게 만듭니다. 습관에 의존하지 말고 의도적으로 값을 선택하세요.
  • max_tokens(또는 클라이언트가 노출하는 동등한 출력 길이 상한) — 생성 길이 상한. 지연 시간과 비용 제어 모두에 유용합니다.
  • top_p — 또 다른 무작위성 제어. 실무에서는 temperature나 top_p 중 하나만 조정하고 동시에 둘 다 조정하지 마세요. 그렇지 않으면 동작 변화를 어느 쪽에도 귀속시킬 수 없습니다.
  • stream — true이면 응답이 단일 JSON 문서 대신 서버 전송 이벤트로 증분 도착합니다. 사용자 대상 인터페이스에 아주 적합하지만 올바르게 파싱하려면 작업이 더 듭니다.
  • stop — 생성을 조기에 끝내는 하나 이상의 시퀀스.

다중 턴 대화에 대한 설명

API는 상태가 없습니다. 요청 간에 아무것도 유지되지 않습니다. 대화를 이어가려면 매번 전체 messages 배열을 다시 보내며, 이전 어시스턴트 응답과 새 사용자 메시지를 추가해야 합니다. 따라서 긴 대화는 요청 본문을 키우고 토큰 사용량도 함께 키웁니다 — 채팅 기능을 설계할 때 이 점을 예산에 넣으세요.

처음에는 요청 본문을 간결하게 유지하세요

필수 필드 두 개로 시작해 합리적인 응답을 받는지 확인하세요. 그런 다음 매개변수를 하나씩 추가하며 차이를 관찰하세요. 최근의 알려진 정상 기준선이 있으면 디버깅이 훨씬 쉬워집니다.

사용 가능한 curl 요청

다음은 완전히 실행 가능한 요청입니다. 지역이나 플랜이 다르면 기본 URL을 플랫폼 API 문서에 표시된 URL로 바꾸고, HIAPI_API_KEY가 현재 셸에 export되어 있는지 확인하세요.

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol@azure",
    "messages": [
      { "role": "system", "content": "You are a concise technical assistant." },
      { "role": "user", "content": "Give me three practical uses for idempotency keys." }
    ],
    "temperature": 0.3
  }'

각 플래그의 역할

  • -sS 진행률 표시줄은 숨기되 오류는 인쇄합니다 — 따라서 실패가 보이지 않는 일은 없습니다.
  • -X POST 메서드를 명시적으로 설정하며, 주로 가독성을 위한 것입니다.
  • Authorization 헤더가 환경에서 가져온 bearer 토큰을 담습니다.
  • Content-Type: application/json은 필수입니다. 이것이 없으면 서버는 본문을 어떻게 파싱해야 할지 알 수 없습니다.
  • -d가 JSON 페이로드를 제공합니다. 셸이 내부의 큰따옴표를 해석하지 않도록 작은따옴표로 감싸세요.

응답 읽기

성공한 호출은 choices 배열을 담은 JSON을 반환합니다. 원하는 텍스트는 choices[0].message.content에 있습니다. 프롬프트와 완성 토큰 수를 담은 usage 객체도 있습니다 — 이것을 기록하세요. 소비가 예상치 못하게 되기 전에 그 추세를 관찰하는 유일하게 저렴한 방법이기 때문입니다.

터미널과 씨름하지 않고 구조를 바로 보고 싶다면 포매터로 파이프하세요:

curl -sS -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol@azure","messages":[{"role":"user","content":"Say hello."}]}' \
  | python3 -m json.tool

이 한 줄은 새 키에 대해 가능한 가장 빠른 스모크 테스트입니다. 애플리케이션 코드를 건드리기 전에 실행하세요 — 실패한다면 문제는 자격 증명이나 연결성에 있지, 여러분의 프로그램에 있지 않습니다.

Python에서의 동일한 요청

requests 버전은 짧지만 신중하게 작성해야 합니다: 응답 본문을 파싱하기 전에 상태 코드를 확인하세요. 오류 응답의 구조는 성공 응답과 다르므로, choices에 바로 접근하면 혼란스러운 KeyError가 발생합니다.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/chat/completions"

payload = {
    "model": "gpt-5.6-sol@azure",
    "messages": [
        {"role": "system", "content": "You are a concise technical assistant."},
        {"role": "user", "content": "Give me three practical uses for idempotency keys."},
    ],
    "temperature": 0.3,
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

if response.status_code != 200:
    # Surface the status and the server's error body, not just the exception.
    print(f"HTTP {response.status_code}: {response.text}")
    response.raise_for_status()

data = response.json()
text = data["choices"][0]["message"]["content"]
print(text)
print(json.dumps(data.get("usage", {}), indent=2))

중요한 세 가지 세부 사항

data=json.dumps(payload) 대신 json=payload를 사용하세요. 딕셔너리를 json=에 넘기면 콘텐츠 타입 헤더를 대신 설정하고 매번 올바르게 직렬화합니다. 수동 직렬화가 대부분의 형식 오류 요청 본문의 원인입니다.

항상 timeout을 설정하세요. 없으면 정체된 요청이 작업 프로세스를 무기한 매달리게 합니다. 넉넉한 타임아웃이라도 없는 것보다 훨씬 낫습니다.

실패 시 response.text를 인쇄하세요. 오류 본문에는 필요한 세부 정보 — 오류 유형, 코드, 사람이 읽을 수 있는 메시지 — 가 담겨 있습니다. raise_for_status()의 예외 메시지만 로그로 남기면 그 정보를 버리게 되어 추측에 의존해야 합니다.

함수로 감싸기

호출이 작동하면 messages 배열을 인수로 받아 콘텐츠 문자열을 반환하는 함수로 승격하세요. 애플리케이션 코드를 깔끔하게 유지하고, 나중에 모델 이름, 타임아웃, 재시도 정책을 바꿀 정확히 한 곳을 제공합니다.

흔한 오류 문제 해결

실패한 첫 호출은 거의 모두 네 가지 범주 중 하나에 속합니다. 다음은 이를 빠르게 구분하는 방법입니다.

인증 실패

증상: 401 응답, 또는 키는 유효하지만 요청한 리소스에 접근 권한이 없으면 403.

순서대로 확인하세요:

  1. HIAPI_API_KEY가 실제로 요청을 보내는 셸이나 프로세스에 설정되어 있나요? echo $HIAPI_API_KEY가 내용을 인쇄해야 합니다.
  2. 헤더에 리터럴 단어 Bearer와 키 앞의 정확히 공백 하나가 포함되어 있나요?
  3. 키가 복사-붙여넣기로 인해 후행 개행이나 따옴표를 포함하고 있나요? 깨끗하게 다시 export하세요.
  4. 복사한 이후 키가 폐기되거나 교체되었나요? 새로 발급하세요.

알 수 없는 모델 식별자

증상: 400 또는 404, 메시지에 모델을 언급.

흔한 원인은 오타, 대소문자 불일치, 또는 문자열 내의 불필요한 공백입니다. gpt-5.6-sol@azure는 정확해야 합니다 — @, 하이픈, 소문자 표기가 모두 중요합니다. 설정 파일이나 환경 변수에서 모델 이름을 읽는다면 그 값과 길이를 인쇄하세요. 보이지 않는 공백이 흔한 원인입니다.

형식이 잘못된 요청 본문

증상: 400, JSON 파싱 또는 누락된 필드에 대한 불만.

  • 오류가 파싱을 언급하면 요청 본문이 유효한 JSON이 아닙니다. curl에서는 페이로드를 작은따옴표로, 키를 큰따옴표로 감싸세요. Python에서는 json=payload를 사용하세요.
  • messages를 언급하면 맨 문자열이 아니라 role과 content를 가진 객체 배열을 전달했는지 확인하세요.
  • model 누락을 언급하면 키 철자가 틀렸거나 중첩 계층이 잘못된 것입니다.

빠른 정합성 검사: 보내기 전에 페이로드를 JSON 검증기에 넣어 보세요. 몇 초 만에 이 범주 전체를 제거할 수 있습니다.

속도 제한 및 할당량

증상: 429 응답, 때때로 retry-after 힌트 포함.

이는 요청이 올바르게 구성되고 인증되었지만 너무 빨리 도착했거나 할당량을 초과했다는 뜻입니다. 해결 방법은 타이트한 루프에서 즉시 재시도하는 것이 아닙니다 — 그것은 상황을 악화시킬 뿐입니다. 지터를 적용한 지수 백오프를 사용하고, 시도 횟수를 제한하고, 지속적인 429는 동시성 수준을 살펴보라는 신호로 보세요.

서버 측 오류

500 또는 502는 여러분의 잘못이 아닙니다. 백오프로 재시도하세요. 지속된다면 에스컬레이션 전에 전체 요청 ID와 응답 본문을 확보하세요 — 이러한 세부 정보가 지원 대화를 생산적으로 만듭니다.

범용 디버깅 습관

실패한 모든 호출마다 네 가지를 기록하세요: HTTP 상태, 응답 본문, 엔드포인트 경로, 모델 이름. API 키는 기록하지 마세요. 이 네 가지 정보로 몇 초 만에 위의 모든 범주를 구분할 수 있으며, 맨 예외 메시지로는 좀처럼 불가능합니다.

첫 성공 호출 이후의 다음 단계

스모크 테스트가 내용을 반환하면 작동하는 연동을 갖게 된 것입니다. 다음은 이를 지속 가능하게 만드는 방법입니다.

의도적으로 매개변수 조정하기

사용 사례에 맞는 temperature를 선택하고 이유를 적어 두세요. 추출 및 분류 작업은 보통 낮은 무작위성을 원하고, 브레인스토밍은 더 많은 무작위성을 원합니다. 결과를 귀속시킬 수 있도록 실험마다 한 매개변수만 변경하세요. 스트리밍을 고려 중이라면 일찍 프로토타이핑하세요 — 응답 파싱 차이가 충분히 커서 나중에 개조하는 것이 처음부터 사용하는 것보다 더 수고롭습니다.

재시도와 타임아웃을 사후 고려가 아닌 정책으로

429 및 5xx 응답에만 지수 백오프를 사용한 재시도 래퍼로 호출을 감싸세요. 400이나 401은 절대 재시도하지 마세요 — 요청이나 자격 증명이 잘못된 것이므로 재시도는 시간만 낭비합니다. 모든 요청에 클라이언트 타임아웃을 설정하고, 사용자 흐름에는 전체 데드라인을 고려하세요.

첫날부터 비용과 지연 시간 모니터링하기

usage 블록을 자체 지연 시간 측정과 함께 기록하세요. 토큰 수는 모든 비용 논의의 입력이고, 지연 시간은 모든 사용자 경험 논의의 입력입니다. 이것이 없으면 맹목적으로 최적화하게 됩니다.

모델 이름을 설정에 두기

세 개의 파일에 gpt-5.6-sol@azure를 하드코딩하는 것이 마이그레이션을 고통스럽게 만드는 방법입니다. 하나의 설정 값에 보관하면 모델 전환은 한 줄 변경이 됩니다 — 이는 플랫폼에서 모델을 공정하게 비교하는 방법이기도 합니다.

키를 적절한 키 관리로 이동하기

노트북의 환경 변수에서 시작했다면, 프로덕션 경로는 런타임에 주입되는 관리형 시크릿 저장소입니다. 동일한 코드, 더 안전한 보관.

출력 경로 강화하기

모델 출력은 신뢰할 수 없는 입력입니다. HTML로 렌더링한다면 이스케이프하세요. JSON으로 파싱한다면 조치 전에 검증하세요. 다운스트림 시스템으로 라우팅한다면 응답이 비었거나 잘렸을 때 어떻게 할지 명시적으로 결정하세요.

플랫폼에서 다른 모델 대상을 탐색할 준비가 되면 동일한 요청 구조를 사용합니다 — model 문자열만 바뀌므로 위에서 구축한 모든 것이 그대로 유지됩니다.

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

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

API 문서 보기