hiapi API로 gpt-6-astra 사용하는 방법: curl, Python 및 실행 가능한 요청 예제

gpt-6-astra는 추론 능력을 갖춘 텍스트 모델로, 현재 hiapi에 출시되어 OpenAI 호환 엔드포인트인 /v1/responses를 통해 접근할 수 있습니다. 본 가이드는 실행 가능한 curl 및 Python 요청 예제, 많은 사람이 놓치는 비직관적인 요구 사항(반드시 스트리밍 사용), 그리고 출시 전에 필요한 프로덕션 실천 패턴을 제공합니다.

무엇을 구축하게 되는가

gpt-6-astra에 프롬프트를 보내고 스트리밍 응답을 통해 모델의 답변을 읽는 스크립트입니다. 여기에는 폴링도, 작업 ID도 없습니다. 이것은 동기식 채팅형 호출이지만, 블로킹 방식의 JSON 응답이 아니라 Server-Sent Events 형태로 전달됩니다.

사전 조건: hiapi API 키. 콘솔에서 발급받으세요. 아래의 모든 요청은 Authorization 헤더에 이를 담아야 합니다.

최소 실행 예제

gpt-6-astra는 하나의 엔드포인트(POST /v1/responses)만 지원하며 "stream": true만 허용합니다. 요청 페이로드에 다른 내용이 무엇이 있든 "stream": false를 보내면 400 invalid_request 오류가 반환됩니다. 해당 모델은 hiapi에서 비스트리밍 모드가 없습니다. 클라이언트는 단일 JSON 응답이 아니라 이벤트 스트림을 읽는 것을 중심으로 설계하세요.

curl

curl -N -X POST "https://api.hiapi.ai/v1/responses" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "AI가 생성한 답변을 원본과 대조하는 실용적인 방법 하나를 설명해 주세요." }
        ]
      }
    ],
    "stream": true,
    "store": false,
    "reasoning": { "effort": "medium" }
  }'

-N은 curl의 출력 버퍼링을 비활성화하여 이벤트가 도착하는 즉시 확인할 수 있게 합니다(마지막에 한꺼번에 받는 대신). 응답类型은 text/event-stream이며, 각 data: 줄은 JSON 객체이고 event: 줄이 그 유형을 표시합니다. 간단히 실행한 결과는 다음과 같습니다:

event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress", ...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"OK", ...}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed","usage":{"input_tokens":12,"output_tokens":5,"total_tokens":17}, ...}}

실제로 원하는 텍스트는 반복적으로 나타나는 response.output_text.delta 이벤트를 통해 스트리밍됩니다. delta 필드를 순서대로 이어 붙이면 완전한 답변이 됩니다. response.completed는 비용 추적을 위한 최종 usage 블록을 함께 전달합니다.

Python

import json
import requests

payload = {
    "model": "gpt-6-astra",
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "AI가 생성한 답변을 원본과 대조하는 실용적인 방법 하나를 설명해 주세요.",
                },
            ],
        },
    ],
    "stream": True,
    "store": False,
    "reasoning": {"effort": "medium"},
}

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json=payload,
    stream=True,
    timeout=60,
) as resp:
    resp.raise_for_status()
    answer = []
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        event = json.loads(line[len(b"data: "):])
        if event.get("type") == "response.output_text.delta":
            answer.append(event["delta"])
        elif event.get("type") == "response.completed":
            usage = event["response"]["usage"]
            print(f"\n\ntokens: {usage['input_tokens']} in / {usage['output_tokens']} out")

    print("".join(answer))

resp.raise_for_status()는 SSE 줄을 파싱하기 시작하기 전에 HTTP 수준의 실패(인증, 요율 제한)를 잡아냅니다. 형식이 잘못된 스트림과 거부된 요청은 서로 다른 실패 모드이므로 오류 처리에서 이 둘을 구분해야 합니다.

요청 페이로드에서 특별히 짚을 만한 두 필드는 다음과 같습니다:

• input은 평면 문자열이 아니라 메시지 객체의 배열입니다. 각 항목에는 type: "message", role, 그리고 타입이 지정된 부분으로 구성된 콘텐츠 배열(일반 텍스트는 input_text)이 필요합니다.
• reasoning.effort(low / medium / high)는 선택 사항이지만, 모델이 답변 전에 얼마나 많은 내부 추론을 수행할지를 제어합니다. 설정하지 않으면 hiapi가 기본값을 적용합니다. 지연과 답변 품질을 저울질해야 한다면 명시적으로 설정하세요.

프로덕션 고려 사항

• 스트리밍은 선택 사항이 아닙니다.재시도 시 stream: false로 폴백하는 코드 경로를 만들지 마세요. 해당 모델에서는 매번 실패합니다. 프레임워크나 SDK가 단일 JSON 응답을 가정한다면, 위의 SSE 루프를 감싸고 이어 붙인 텍스트를 버퍼링한 뒤 넘기세요.
• 인증 실패는 명확합니다.유효하지 않거나 폐기된 키는 HTTP 401과 함께 오류 본문에 "code": "permission_denied"를 담아 반환합니다. 메시지 문자열은 바뀔 수 있으므로 문자열 패턴 매칭 대신 해당 코드를 확인하세요.
• store: false는 요청을 무상태로 만듭니다.hiapi는 응답을 서버 측에 보관하지 않으므로, 후속 호출에서 연결할 previous_response_id를 사용할 수 없습니다. 다중 턴 컨텍스트가 필요하면 서버 측 대화 상태에 의존하지 말고 이전 턴을 추가 input 메시지로 다시 전송하세요.
• 스트리밍 여부와 관계없이 클라이언트 타임아웃을 설정하세요.SSE 연결은 양쪽 어디에서도 깔끔한 종료 신호를 보내지 않은 채 끊기면 멈춰 있을 수 있습니다. 초기 requests.post에 timeout을 설정하면(위 예제처럼) 첫 바이트 정체를 방지할 수 있지만, 심층 방어를 위해 자체 코드에서 최대 스트림 지속 시간도 추적해야 합니다.
• 반복되는 시스템 컨텍스트에는 prompt_cache_key를 재사용하세요.응답 페이로드에는 prompt_cache_key가 포함됩니다. 매 호출마다 동일한 지시를 보낸다면 요청을 같은 키에 유지하여 hiapi가 매번 다시 처리하는 대신 프롬프트 캐시를 적용하게 하세요.

관련 자료

• gpt-6-astra 모델 페이지 — 전체 파라미터 레퍼런스 및 실시간 가격
• hiapi API 문서 — 인증, 기타 모델 계열 및 전체 엔드포인트 목록
• hiapi 가격 — gpt-6-astra 및 기타 모든 모델의 토큰당 요율

자주 묻는 질문

gpt-6-astra는 /v1/chat/completions를 지원하나요? 아니요. /v1/chat/completions로 호출하면 400 unsupported_endpoint 오류가 반환되며, /v1/responses를 사용하라고 안내합니다. hiapi에서는 Responses API용으로만 등록되어 있습니다.

스트림 대신 단일 JSON 응답을 받을 수 있나요? 해당 모델에서는 불가능합니다. "stream": false는 다른 파라미터 설정 여부와 관계없이 곧바로 거부됩니다(invalid_request). 위에서 보여준 것처럼 SSE 스트림을 소비하고 클라이언트에서 최종 텍스트를 조립하는 것을 중심으로 통합을 구축하세요.

gpt-6-astra는 도구 호출을 지원하나요? 해당 모델은 Responses API 요청 구조에서 tools 배열을 받습니다(설정하지 않으면 응답 객체에 빈 배열로 표시됨). 함수 호출을 연결하려면 OpenAI Responses API 호환 모델과 동일한 방식으로 도구를 정의하고, 스트림에서 function_call 유형의 response.output_item.added 이벤트를 주의하세요.

요율 제한 또는 할당량 오류는 어떻게 생겼나요? 다른 hiapi 오류와 마찬가지로 type: "hiapi_error"와 분기 처리에 사용할 수 있는 code 필드, 그리고 request_id를 담은 JSON으로 반환됩니다. 지원팀에 문의할 때 이 ID를 포함하면 서버 측에서 정확한 요청을 추적할 수 있습니다.

hiapi의 다른 추론 모델에서도 동일한 요청 구조를 사용할 수 있나요? /v1/responses 요청 구조는 hiapi의 OpenAI Responses 호환 모델 계열에서 공유됩니다. model 필드만 교체하면 모델을 전환할 수 있습니다. 가용성은 모델마다 다르므로, 해당 모델이 출시되었다고 가정하기 전에 그 모델의 페이지를 확인하세요.