HiAPI API로 gpt-5.6-terra@azure를 호출하는 방법: curl 및 Python 가이드

gpt-5.6-terra@azure가 HiAPI 요청에서 의미하는 것

HiAPI 요청에서 gpt-5.6-terra@azure는 모델 식별자입니다. 채팅 요청 본문의 model 필드에 넣으면 됩니다. 이것이 사용자 측에서 지켜야 할 약속의 전부입니다. 서비스 제공자 전용 URL을 구성할 필요도, SDK를 교체할 필요도, 요청 본문 구조를 바꿀 필요도 없습니다.

@azure 접미사는 라우팅 메타데이터로, HiAPI에 이 모델의 해당 변형 요청을 어느 백엔드가 처리해야 하는지 알려줍니다. 요청 본문의 나머지 요소인 messages, temperature, max_tokens, stream, tools는 모두 이미 익숙한 표준 chat-completions 구조를 그대로 유지합니다. 이는 실무에서 중요합니다. HiAPI에서 다른 모델을 호출하는 동작하는 요청이 이미 있다면, gpt-5.6-terra@azure로 마이그레이션하는 데는 보통 한 줄 수정이면 충분합니다.

{
  "model": "gpt-5.6-terra@azure",
  "messages": [
    { "role": "user", "content": "Hello" }
  ]
}

두 가지 습관을 들이면 모델 ID 관련 버그가 거의 발생하지 않습니다:

• ID를 불투명 문자열로 취급하십시오. @와 소문자 접미사를 포함해 그대로 복사하십시오. 공백을 넣지 말고, 대소문자를 바꾸지 마십시오.
• 코드 곳곳에 흩어 놓지 말고 설정에 두십시오. 상수나 환경 변수를 사용하면 서로 다른 모델 ID 간의 A/B 테스트가 리팩터링이 아니라 설정 변경이 됩니다.

접미사가 라우팅을 담당하므로, ID만으로 하위 서비스 스택에 대해 어떤 것도 추론해서는 안 됩니다. 지연 시간, 한도, 지원 파라미터는 HiAPI가 해당 모델을 노출할 때 갖는 속성이므로, 작은 요청으로 실제 동작을 먼저 검증한 뒤 가정을 애플리케이션에 반영하십시오.

사전 준비와 키 준비하기

첫 호출 전에 세 가지를 확인하십시오:

1. HiAPI 계정. 로그인해야 자격 증명을 생성하고 콘솔에서 현재 모델과 가격 정보를 확인할 수 있습니다.
2. API 키. 콘솔에서 생성해 안전한 곳에 보관하십시오. 비밀번호처럼 다루십시오. 본 가이드는 특정 키 형식을 가정하지 않습니다. 콘솔이 제공하는 문자열이 곧 Authorization 헤더에 넣을 값입니다.
3. HTTP 클라이언트. 빠른 검증에는 curl, 애플리케이션 코드 작성에는 Python 3와 requests 또는 OpenAI 호환 SDK를 사용하십시오.

키를 소스 파일에서 멀리 두기

환경 변수를 사용하십시오. 이 패턴은 모든 플랫폼에서 동일합니다:

export HIAPI_API_KEY="your-key-here"

그런 다음 런타임에 참조하십시오. 셸에서는 "$HIAPI_API_KEY", Python에서는 os.environ["HIAPI_API_KEY"]입니다. CI에서는 .env 파일을 커밋하지 말고 서비스 제공자가 제공하는 비밀 저장소를 사용하십시오.

디버깅을 위해 키를 터미널에 붙여 넣었다면 셸 기록에 남을 수 있음을 기억하십시오. 실제 자격 증명이라면 나중에 교체하십시오. 로컬 개발에는 테스트 전용 일회성 키를 사용하는 편이 운영 자격 증명을 재사용하는 것보다 관리하기 쉽습니다.

Base URL과 엔드포인트 확인

HiAPI는 OpenAI 호환 chat completions 엔드포인트를 제공합니다. 콘솔 문서에서 base URL과 경로를 가져와 curl과 Python에서 일관되게 유지하십시오. "curl은 되는데 Python은 안 된다"는 보고의 대부분은 결국 끝의 슬래시나 누락된 경로 세그먼트 문제입니다.

동작하는 curl 요청

아래는 최소한의 올바른 호출입니다. base URL을 콘솔에 표시된 것으로 바꾸고 HIAPI_API_KEY가 내보내졌는지 확인하십시오.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra@azure",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain what an API gateway does in two sentences."}
    ],
    "max_tokens": 200
  }'

필드별 설명:

• -sS는 진행 표시를 숨기되 오류는 계속 표시합니다. 응답 헤더를 본문과 함께 보고 싶다면 -i를 추가하십시오.
• Authorization: Bearer $HIAPI_API_KEY는 요청을 인증합니다. Bearer 접두사와 공백이 모두 필요합니다.
• Content-Type: application/json — 생략하면 많은 서버가 본문을 파싱하기도 전에 거부합니다.
• model — 정확한 ID gpt-5.6-terra@azure입니다.
• messages — 순서가 있는 배열입니다. system은 동작을 설정하고 user는 프롬프트를 담습니다. 다중 턴 대화는 assistant와 user 턴을 순서대로 추가하십시오.
• max_tokens — 응답 길이의 상한입니다. 빠른 검증에서는 작게 유지하면 실패 비용이 낮고 빠릅니다.

성공 응답은 choices 배열을 포함한 JSON이며, 필요한 텍스트는 choices[0].message.content에 있습니다. 처음 몇 번은 출력을 JSON 포매터로 처리해 구조를 확인하십시오. 긴 한 줄을 힘들게 들여다볼 필요가 없습니다.

이 요청이 동작하면 환경 변수에서 키를 읽는 셸 스크립트로 저장하십시오. 그러면 모델 ID나 파라미터를 바꿀 때마다 실행할 수 있는 반복 가능한 상태 점검이 생깁니다.

동등한 Python 요청

요청 본문은 완전히 동일합니다. 전송 방식만 다릅니다. requests를 사용하십시오:

import os
import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain what an API gateway does in two sentences."},
    ],
    "max_tokens": 200,
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

유지할 만한 세부 사항이 세 가지 있습니다. 수동 직렬화 대신 json=payload를 사용하고(헤더와 인코딩을 알아서 설정합니다), 항상 timeout을 설정하며, raise_for_status()를 호출해 4xx나 5xx가 오류 응답 본문을 인덱싱할 때의 IndexError가 아니라 예외로 드러나게 하십시오.

서비스 제공자 SDK 스타일

이 엔드포인트는 OpenAI와 호환이므로, 사용자 정의 base URL로 구성한 SDK는 동일한 요청을 생성합니다:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Say hello in one word."}],
    max_tokens=50,
)
print(completion.choices[0].message.content)

두 방식을 모두 보여 주는 이유는 이것입니다. 모델 ID는 어떤 모델이 당신을 위해 서비스하는지를 식별하는 유일한 변수입니다. 나머지는 평범한 chat-completions 파이프라인이므로, 로직을 다시 작성하지 않고 원시 HTTP와 SDK를 오갈 수 있습니다.

스트리밍과 도구 호출 추가하기

이 두 기능은 점진적입니다. 기본 요청을 다시 작성하는 것이 아니라 필드를 추가하고 응답을 소비하는 방식을 바꾸는 것입니다.

스트리밍

요청 본문에 "stream": true를 설정하십시오:

stream = client.chat.completions.create(
    model="gpt-5.6-terra@azure",
    messages=[{"role": "user", "content": "Count from 1 to 10."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

응답은 단일 JSON 객체가 아니라 서버 전송 이벤트의 연속이 됩니다. 각 청크는 콘텐츠 조각을 담은 delta를 가집니다. 첫 번째와 마지막 청크에서는 delta.content가 None일 수 있으므로 이어 붙이기 전에 확인하십시오. 원시 HTTP에서도 마찬가지입니다. 응답 본문을 한 줄씩 읽고 data: 접두사를 제거하고 [DONE]을 건너뛰며 각 JSON 줄을 파싱하십시오.

도구 호출

요청에 도구를 설명하고 모델이 언제 호출할지 결정하게 하십시오:

payload = {
    "model": "gpt-5.6-terra@azure",
    "messages": [{"role": "user", "content": "What's the weather in Berlin?"}],
    "tools": [{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }],
    "tool_choice": "auto",
}

모델이 도구를 호출하려 할 때 choices[0].message는 일반 텍스트 대신 tool_calls 배열을 포함합니다. 각 항목에는 id와 function이 있으며, function에는 name과 arguments(직접 파싱해야 하는 JSON 문자열)가 있습니다. 함수를 실행한 다음 role: "tool" 메시지로 결과를 반환하되, 일치하는 tool_call_id와 직렬화된 출력을 함께 담아 다시 요청하여 최종 답변을 받으십시오.

tool_choice는 "auto"(모델이 결정), "none"(텍스트만) 또는 지정된 함수를 받습니다. 스트리밍과 도구는 함께 사용할 수 있지만, 도구 호출 인자는 청크에 걸쳐 조각으로 도착하므로 먼저 누적한 뒤 파싱해야 합니다. 먼저 비스트리밍 도구 호출을 동작시키십시오.

일반적인 요청 오류 진단

다음 순서로 디버깅하십시오. 각 단계가 한 계층을 격리하므로 두 문제를 동시에 추적하지 않게 됩니다.

1. 인증(401 / 403)

가장 가능성 높은 원인은 키 누락, Bearer 접두사 탈락, 또는 환경 변수가 빈 문자열로 확장된 경우입니다. 전체 키를 인쇄하지 않고 헤더 구성 방식을 에코로 확인하고, 변수가 요청을 실행하는 같은 셸이나 프로세스에 설정되어 있는지 확인하십시오.

2. 엔드포인트와 경로(404)

404는 보통 경로가 잘못되었음을 의미합니다. 오타, /v1 누락, 또는 있어서는 안 될 곳의 끝 슬래시입니다. 다시 입력하지 말고 콘솔에서 정확한 URL을 복사하십시오.

3. 모델 ID(400, 모델 관련 메시지 포함)

ID는 정확히 일치해야 합니다: gpt-5.6-terra@azure. 흔한 실수로는 대소문자 변경, @azure 누락, 복사-붙여넣기로 인한 추가 공백이 있습니다. 메시지가 모델을 알 수 없다고 하면 서비스 장애를 의심하기 전에 구성된 문자열을 콘솔 목록과 문자 단위로 비교하십시오.

4. 요청 본문 형식 오류(400 / 422)

오류가 요청 본문을 언급하면 먼저 JSON 유효성을 확인하십시오. 끝의 쉼표나 이스케이프되지 않은 인용 부호가 흔한 원인입니다. 그런 다음 필드명(message가 아니라 messages)과 역할(system, user, assistant, tool)을 점검하십시오. max_tokens는 숫자여야 하고, tools는 구조가 올바른 객체 배열이어야 합니다.

5. 스트리밍 응답을 일반 JSON으로 처리

출력이 비었거나 깨졌거나 파싱 오류가 발생하면, stream: true로 요청했으면서 응답을 단일 JSON 문서로 파싱했을 가능성이 큽니다. 이벤트 스트림으로 읽고 [DONE]을 건너뛰며 None delta에 대비하십시오.

6. 클라이언트 타임아웃

긴 생성은 기본 HTTP 타임아웃을 초과할 수 있습니다. 클라이언트에서 명시적으로 늘리거나 스트리밍으로 전환해 바이트가 즉시 도착하기 시작하게 하십시오.

빠른 재현 체크리스트

• 최소화한 curl 호출을 실행하십시오. 성공하면 문제는 당신의 코드에 있습니다.
• 실패하면 새 셸에서 키와 모델 ID로 다시 시도하십시오.
• HTTP 상태 코드와 응답 본문을 모두 기록하십시오. 오류 응답 본문에 진단 세부 정보가 있습니다.
• 이 검사들을 모두 통과한 뒤에야 서버 측 문제를 에스컬레이션할 가치가 있다고 의심하십시오.

동작하는 요청, 스트리밍 루프, 이 체크리스트가 있으면 gpt-5.6-terra@azure는 당신의 기술 스택에서 다른 채팅 모델과 똑같이 동작합니다. 그리고 모델 전환은 설정의 한 줄 변경이 됩니다.