HiAPI로 gpt-6.1 Sol 호출하기: curl, Python, 스트리밍 실측 (한국어 튜토리얼)

이 글의 목표와 전제

이 글을 다 읽으면 HTTP 요청 하나로 gpt-6.1 Sol을 실행할 수 있게 됩니다. HiAPI의 GPT-6.1 Sol 패밀리 중 복잡한 프로그래밍, 문서 분석, 다단계 추론에 특화된 텍스트 모델이며, 스트리밍으로 반환되는 텍스트를 받게 됩니다. 그대로 복사해 쓸 수 있는 curl과 Python 예제, 그리고 가장 많이 걸리는 세 가지 함정을 알려드립니다: 엔드포인트는 /v1/responses이고(/v1/chat/completions 아님), 스트리밍을 반드시 켜야 하며, input은 반드시 배열이어야 합니다.

전제: HiAPI API Key 하나. API 키 페이지에서 생성해 안전하게 보관하고, 모든 요청에 Authorization: Bearer sk-<你的 key>로 전송하세요.

gpt-6.1 Sol은 순수 텍스트 모델(대화 / 추론 / 프로그래밍)이며 이미지를 생성하지 않습니다. 기능 설명과 온라인 체험은 gpt-6.1 Sol 모델 페이지를 참고하세요.

최소 실행 예제

Sol 패밀리는 Responses API를 사용합니다: POST /v1/responses. 두 가지 필수 규칙 중 하나라도 빠지면 400이 납니다:

1. "stream": true —— 모델은 스트리밍만 지원하며, stream:false는 거부됩니다.
2. input은 메시지 객체 배열 —— 스트리밍을 켠 상태에서 문자열을 그대로 전달하면 input: has incorrect type 오류가 납니다.

curl

curl -N https://api.hiapi.ai/v1/responses \
  -H "Authorization: Bearer sk-<你的 key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          { "type": "input_text", "text": "API 속도 제한이 무엇인지 한 문장으로 설명해 줘." }
        ]
      }
    ],
    "stream": true
  }'

-N은 curl의 출력 버퍼링을 끄는 옵션이라 Server-Sent Events(SSE)가 하나씩 반환되는 것을 실시간으로 볼 수 있습니다. 스트림은 event: / data: 줄의 연속이며, 원하는 본문은 response.output_text.delta 조각에 나타나고, 최종 상태의 response.completed 이벤트에서 전체가 다시 한 번 반복됩니다.

축약형 "input": [{"role":"user","content":"……"}]도 정상 동작합니다. 위의 type/input_text 정식 표기는 멀티모달이나 멀티턴을 조합할 때 더 안정적이므로 기본으로 쓰기를 권장합니다.

Python

SDK가 필요 없습니다. HiAPI는 일반 HTTP이므로 requests에 stream=True를 켜면 됩니다:

import json
import requests

API_KEY = "sk-<你的 key>"

payload = {
    "model": "gpt-6.1-sol",
    "input": [
        {
            "type": "message",
            "role": "user",
            "content": [
                {"type": "input_text", "text": "API 속도 제한이 무엇인지 한 문장으로 설명해 줘."}
            ],
        }
    ],
    "stream": True,
}

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    stream=True,
    timeout=120,
) as resp:
    resp.raise_for_status()

    text = ""
    for line in resp.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data:"):
            continue
        event = json.loads(line[len("data:"):].strip())
        etype = event.get("type")
        if etype == "response.output_text.delta":
            text += event["delta"]
        elif etype == "response.completed":
            usage = event["response"]["usage"]
            print(f"\n[tokens: in={usage['input_tokens']} "
                  f"out={usage['output_tokens']} total={usage['total_tokens']}]")

print(text)

JSON에 포함된 type 필드로 분기하는 편이(event: 줄을 파싱하는 대신) 더 안정적입니다. 각 SSE 프레임은 event: <type>와 data: <json> 두 줄로 구성되므로, data: 줄만 필터링하고 event["type"]을 읽으면 충분합니다.

프로덕션 환경 요점

• 스트리밍 모드만 있습니다. 비스트리밍 변형이 없고 stream:false는 곧바로 400입니다. 클라이언트는 처음부터 SSE를 전제로 설계해야 합니다: 읽기 타임아웃을 추가하고, 스트림이 끊기면 재연결 / 재시도하세요.
• max_output_tokens를 전달하지 마세요. 이 실행 프로파일은 해당 파라미터를 받지 않습니다(not supported by this execution profile 오류). 길이를 제어하려면 prompt나 시스템 지시에서 제약하세요. 모델은 한 번에 최대 약 12.8만 토큰을 출력할 수 있지만, 이 상한은 파라미터로 설정할 수 없습니다.
• 시스템 프롬프트는 메시지에 넣지 말고 최상위 instructions(문자열)에 두세요:

{
  "model": "gpt-6.1-sol",
  "instructions": "당신은 간결한 어시스턴트이며 한 문장으로만 답합니다.",
  "input": [
    { "type": "message", "role": "user",
      "content": [{ "type": "input_text", "text": "webhook이 뭐야?" }] }
  ],
  "reasoning": { "effort": "low" },
  "stream": true
}

• reasoning.effort로 추론 깊이와 비용을 조율하세요. gpt-6.1 Sol은 추론형 모델이며 reasoning.effort는 low / medium / high / xhigh / max 다섯 단계를 지원하고 기본값은 medium입니다. 단계가 낮을수록 소비하는 추론 토큰이 적습니다. 그리고 추론 토큰은 출력으로 과금되며, 최종 상태 이벤트의 usage.output_tokens_details.reasoning_tokens에 나타납니다. 낮은 단계로 해결되는 작업에는 높은 단계를 켜지 마세요.
• 구조화된 출력이 필요하면 text.format을 쓰세요. 이 모델은 JSON Schema 엄격 모드(strict)를 지원하므로, prompt로 형식을 기도하는 대신 파싱 가능한 JSON을 안정적으로 내보내게 하기에 적합합니다.
• 도구 호출(function calling)을 지원합니다. 최상위 tools + tool_choice를 사용할 수 있으며, 도구 결과를 대화에 이어 붙여 추론을 계속하는 것도 지원하므로 agent 시나리오에 적합합니다.
• 멀티턴 대화: 이전 user와 assistant 메시지를 순서대로 input 배열에 추가해 다음 요청을 보내면 됩니다.
• 인증 실패는 401입니다. key가 틀리거나 폐기되면 401, code permission_denied("This API key is invalid.")가 반환됩니다. 이 경우엔 곧바로 오류를 던지고 재시도하지 마세요. 재시도로는 잘못된 key를 고칠 수 없습니다. 반환 본문의 request_id는 기술 지원에 문의할 때 사용하세요.
• 과금은 token 기준입니다. input과 output은 각각 과금되며 output 단가가 input보다 확실히 높습니다. 캐시 적중된 입력 토큰은 더 저렴합니다. 추론 토큰은 output에 포함되어 함께 과금됩니다(그래서 reasoning.effort를 낮추는 것이 곧 비용 절감). 한 번의 입력이 약 27.2만 토큰을 넘으면 더 높은 장문맥 가격 구간에 들어갑니다. 구체적인 수치는 가격 페이지를 실시간 기준으로 확인하고, 코드에 가격을 하드코딩하지 마세요.

실측 기록: 실제로 성공한 요청 한 건

이 글의 예제는 문서를 그대로 옮긴 것이 아니라, 위 curl로 /v1/responses를 실제로 한 번 호출한 것입니다(reasoning.effort: low, 프롬프트는 "API 속도 제한이 무엇인지 한 문장으로 설명해 줘"였습니다). 관찰 결과:

• 최종 상태 response.completed 이벤트의 usage: input_tokens=31, output_tokens=28, total_tokens=59, 그중 output_tokens_details.reasoning_tokens=0 —— 낮은 단계 + 간단한 질문에서는 추론 토큰이 0이 될 수 있고, 비용은 거의 보이는 출력 부분뿐입니다.
• 텍스트는 스트림에서 response.output_text.delta로 점진 도착하며, 최종 상태에서 response.output[0].content[0].text로 전체 결과를 한 번에 받을 수 있습니다. 두 방식 모두 가능합니다.
• 반환 본문에 reasoning.effort 메아리, service_tier, prompt_cache_retention 등의 필드가 포함되어 effort와 캐시가 실제로 적용됨을 확인했습니다.

몇 가지 흔한 오류도 실제로 모두 유발해 보았습니다. 대조하며 문제를 찾아보세요(모두 실제 반환값입니다):

무엇을 잘못했나	HTTP	code	message
/v1/chat/completions로 보냄	400	unsupported_protocol	Model does not support this protocol
stream:false를 전달	400	invalid_parameter	stream: must be true
max_output_tokens를 전달	400	invalid_parameter	max_output_tokens: is not supported by this execution profile
input에 문자열을 전달	400	invalid_parameter	input: has incorrect type
key가 유효하지 않음	401	permission_denied	This API key is invalid.(request_id 포함)

한 줄 트러블슈팅 구호: 400이 나면 먼저 이 세 가지를 확인하세요 —— 엔드포인트가 /v1/responses인지, stream이 true인지, input이 배열인지. "호출이 안 된다"의 대부분은 이 세 가지 중 하나입니다.

관련 링크

• gpt-6.1 Sol 모델 페이지 —— 기능, 파라미터, 온라인 체험
• HiAPI 문서 —— API 개요와 더 많은 모델
• 가격 페이지 —— 종량제 실시간 단가
• 아직 모델을 고르는 중인가요? GPT-6 Astra vs GPT-5.6 Sol 선택 가이드와, 마찬가지로 Responses API를 쓰는 GPT-6 Astra 모델 페이지를 참고하세요

자주 묻는 질문

OpenAI 공식 SDK로 바로 연결할 수 있나요? gpt-6.1 Sol은 Responses API 프로토콜을 사용하며 인터페이스 형태도 호환됩니다. 다만 이 글의 예제는 가장 가벼운 순수 HTTP(requests + stream=True)를 쓰므로 어떤 SDK에도 의존하지 않고 그대로 복사해 실행할 수 있습니다. 핵심은 base URL을 https://api.hiapi.ai로 지정하고 HiAPI의 key를 붙이는 것입니다.

왜 stream:false를 전달하면 계속 400이 나나요? 설계상 그렇고, 버그가 아닙니다. Sol 패밀리는 스트리밍만 지원하며 stream은 반드시 true여야 합니다. 그렇지 않으면 invalid_parameter(stream: must be true)가 반환됩니다. 클라이언트를 SSE 읽기 방식으로 바꾸면 됩니다.

출력 길이는 어떻게 제어하나요? max_output_tokens는 사용할 수 없나요? 사용할 수 없습니다. 전달하면 400이 납니다. instructions에 길이 요구사항(예: "한 문장으로만 답하세요")을 명시하거나 prompt에서 제약하세요.

비용은 어떻게 줄이나요? 우선 reasoning.effort를 낮추세요(추론 토큰은 출력으로 과금되므로 낮은 단계가 곧 절감). 시스템 프롬프트를 재사용해 입력이 캐시에 적중되면 더 저렴해지고, 초장문 맥락을 한 번에 넣어 고가 구간을 촉발하는 것을 피하세요. 실시간 단가는 가격 페이지를 참고하세요.