튜토리얼
HiAPI API로 kimi-k3.1-pro-highspeed 호출하는 방법: curl 및 Python 예제
이 페이지에서
kimi-k3.1-pro-highspeed란 무엇이며 언제 선택해야 하는가
kimi-k3.1-pro-highspeed는 HiAPI가 제공하는 채팅형 모델 중 하나입니다. 호출 방식은 플랫폼의 다른 모든 채팅 모델과 동일합니다. 메시지 목록을 보내면 완성 결과를 돌려받습니다. 이름에 담긴 'high-speed'는 의도된 트레이드오프를 드러냅니다. 원시 추론 깊이보다 지연 시간을 중시하고, 가장 느리고 가장 상세한 답변 대신 예측 가능한 응답 시간을 원할 때 선택하면 됩니다.
따라서 다음과 같은 구체적인 워크로드에 잘 맞습니다.
- 대화형 인터페이스 — 채팅 UI, 자동 완성, 인라인 어시스턴트처럼 사용자가 응답을 기다리는 상황.
- 고처리량 파이프라인 — 분류, 추출, 요약, 재작성 작업처럼 처리량이 필요하고 개별 요청 결과가 짧은 경우.
- 멀티홉 에이전트 루프 — 다단계 흐름에서 각 호출은 작고, 전체 지연 시간이 단일 호출이 아니라 왕복 횟수에 주로 좌우되는 경우.
대량의 컨텍스트에서 길고 숙고된 추론이 필요한 작업이거나, 한 번의 느리지만 고품질인 통과가 여러 번의 빠른 통과보다 나은 콘텐츠를 생성하는 경우라면 이 모델이 자명한 선택은 아닙니다. 그런 경우에는 속도를 최적화하기 전에 먼저 출력 품질을 벤치마크하세요. 빠르지만 틀린 답변은 느리지만 맞는 답변보다 비용이 더 큽니다.
이 모델은 HiAPI의 통합 인터페이스를 통해 제공되므로, 이후 다른 모델로 전환하거나 다시 이 모델로 돌아오는 일은 코드를 다시 작성하는 것이 아니라 요청 페이로드를 바꾸는 일입니다. 모델 이름을 호출 지점에 하드코딩하지 않고 설정에 두면 요청 구성 코드를 바꾸지 않고도 다른 모델과 A/B 테스트를 할 수 있습니다.
'채팅형'이 실제로 의미하는 것
모든 요청은 다음 구조를 가집니다. 모델 식별자, 순서가 있는 메시지 목록(각 메시지는 role과 content를 포함), 그리고 stream, temperature, max_tokens 같은 선택적 매개변수입니다. 시스템 프롬프트는 role: "system" 메시지로 전달됩니다. 이것이 전부입니다. 이 가이드의 나머지는 이 형태를 둘러싼 배관 작업일 뿐입니다.
사전 준비: 자격 증명, 엔드포인트, 모델 이름
코드를 작성하기 전에 다음 네 가지를 갖추었는지 확인하세요. 대부분의 첫 호출 실패는 요청 본문의 버그가 아니라 이 목록의 누락에서 비롯됩니다.
1. API 키
HiAPI 계정 대시보드에서 키를 생성하세요. 기밀 정보로 취급하세요. 환경 변수에서 불러오고, 저장소에 절대 커밋하지 말고, 로그나 공유 노트북에 나타나는 즉시 교체하세요.
export HIAPI_API_KEY="your-key-here"
2. 기본 URL
엔드포인트는 HiAPI 기본 URL에 채팅 완성 경로를 붙인 형태입니다. 기본 URL을 설정에 두면 변경 시 코드를 고치지 않아도 됩니다.
export HIAPI_BASE_URL="https://api.hiapi.ai/v1"
3. 모델 식별자
보낼 모델 문자열은 정확히 다음과 같습니다.
kimi-k3.1-pro-highspeed
문자 그대로 복사하세요. 모델 이름은 리터럴하게 일치해야 합니다. 공백이 하나 더 있거나, 대소문자가 다르거나, 철자가 틀리면 다른 필드의 검증 오류가 아니라 모델을 찾을 수 없다는 종류의 오류가 반환되어 엉뚱한 곳에서 디버깅하게 될 수 있습니다.
4. HTTPS를 보낼 수 있는 클라이언트
아래 curl 예제에는 curl이 설치된 셸만 있으면 되며, macOS와 대부분의 Linux 이미지에 기본 포함되어 있습니다. Python 부분에는 Python 3.8+와 requests 패키지가 필요합니다.
pip install requests
SDK 스타일 클라이언트를 선호하더라도 동일한 엔드포인트, 키, 모델 이름이 그대로 적용됩니다. 중요한 것은 전송 형식이므로, 이 가이드는 어떤 것도 추상화 뒤에 숨지 않도록 원시 HTTP를 고수합니다.
정상 작동 확인
전체 요청을 구성하기 전에 키와 기본 URL이 해석되는지 확인하는 빠른 점검을 실행하세요. 의도적으로 최소화한 한 단어 프롬프트 호출입니다. 이것이 성공하면 이후의 모든 실패는 자격 증명이 아니라 요청 페이로드에 관한 것입니다.
사용 가능한 curl 요청
아래는 복사해 바로 붙여넣을 수 있는 완전한 요청입니다. 시스템 메시지로 동작을 설정하고 사용자 메시지로 실제 요청을 전달하며, 테스트 중 응답이 짧게 유지되도록 max_tokens를 고정합니다.
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [
{"role": "system", "content": "당신은 간결한 기술 어시스턴트입니다. 두 문장 이내로 답하세요."},
{"role": "user", "content": "멱등 키가 무엇인지, 그리고 재시도에 왜 중요한지 설명해 주세요."}
],
"temperature": 0.3,
"max_tokens": 200,
"stream": false
}'
필드별 설명
model— 이전 섹션의 모델 식별자입니다. 필수입니다.messages— 순서가 있는 배열입니다.system은 페르소나와 제약을 설정하고user는 작업을 담습니다. 순서가 중요합니다. 뒤쪽 메시지가 동작을 이끄는 데 더 높은 우선순위를 가집니다. 멀티턴 흐름에서는 모든 내용을 하나의 거대한 사용자 메시지로 이어 붙이지 말고 같은 배열에user와assistant턴을 계속 추가하세요.temperature— 샘플링 무작위성입니다. 낮은 값은 추출과 분류에 필요한 더 재현 가능한 출력을 줍니다. 정말로 변화를 원할 때만 높이세요.max_tokens— 생성 응답의 상한입니다. 명시적으로 설정하면 통제 불능의 생성으로부터 보호하고 지연 시간을 예측 가능하게 만듭니다.stream— 여기서는false이므로 생성이 완료되면 JSON 객체 하나를 받습니다. 이후 섹션에서true를 다룹니다.
반환되는 것
응답은 choices 배열을 포함한 JSON 객체입니다. 원하는 텍스트는 choices[0].message.content에 있습니다. 또한 토큰 소비를 설명하는 usage 블록이 있습니다. 토큰 기반 과금에서는 이것이 요청당 비용의 유일한 신호이므로 기록하세요.
디버깅 중이라면 출력을 포매터에 파이프로 넘겨 읽기 쉽게 만드세요.
curl -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | python -m json.tool
요청 본문을 payload.json에 넣고 -d @payload.json을 사용하면 페이로드가 몇 개 필드를 넘는 순간 셸 따옴표 문제를 피할 수 있습니다.
요청을 Python으로 이식하기
여기서 목표는 데모 스크립트가 아니라 임포트 가능한 함수입니다. 요청 페이로드를 curl 버전과 정확히 동일하게 유지하세요. 같은 필드, 같은 이름, 같은 모델 문자열이어야 도구를 바꿔도 동작이 달라지지 않습니다.
import os
import requests
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai/v1")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "kimi-k3.1-pro-highspeed"
def chat(
user_message: str,
system_message: str = "당신은 간결한 기술 어시스턴트입니다.",
temperature: float = 0.3,
max_tokens: int = 400,
timeout: float = 30.0,
) -> str:
payload = {
"model": MODEL,
"messages": [
{"role": "system", "content": system_message},
{"role": "user", "content": user_message},
],
"temperature": temperature,
"max_tokens": max_tokens,
"stream": False,
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=timeout,
)
response.raise_for_status()
data = response.json()
return data["choices"][0]["message"]["content"]
그런 다음:
print(chat("PUT과 PATCH의 차이를 한 문장으로 요약해 주세요."))
이렇게 작성하는 이유
- 직접 작성한 JSON 대신
json=payload사용 — requests가 올바르게 직렬화하고 콘텐츠 타입을 설정하므로 따옴표 버그 부류 전체가 사라집니다. - 명시적
timeout— 이것이 없으면 정체된 연결이 작업 프로세스를 무기한 매달리게 할 수 있습니다. 짧은 완성에는 30초면 충분히 여유 있고, 대화형 경로에서는 더 낮추세요. - 이른
raise_for_status()— HTTP 계층 실패가 세 줄 뒤choices에서KeyError로 터지는 대신 호출 경계에서 예외로 드러나길 원합니다. - 모듈 수준 구성 — 키, 기본 URL, 모델이 한곳에 모입니다. 이후 다른 모델을 A/B 테스트할 때 상수 하나만 바꾸면 됩니다.
멀티턴 대화
실제 대화에서는 두 개의 고정 메시지를 만드는 대신 메시지 목록을 매개변수로 받으세요.
def chat_with_history(messages: list, **kwargs) -> dict:
payload = {"model": MODEL, "messages": messages, "stream": False, **kwargs}
r = requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=30.0,
)
r.raise_for_status()
body = r.json()
return {
"content": body["choices"][0]["message"]["content"],
"usage": body.get("usage"),
}
어시스턴트의 응답을 role: "assistant"로 messages에 다시 추가해 대화를 이어가고, 기록이 길어지면 오래된 턴을 잘라내세요. 컨텍스트도 과금되므로 무제한 대화 기록은 요청마다 비용을 조용히 끌어올립니다.
스트리밍 응답 활성화 및 소비
"stream": true를 설정하면 서버는 마지막에 객체 하나를 보내는 대신 서버 전송 이벤트 형태로 응답을 점진적으로 보냅니다. 사용자가 지켜보는 모든 콘텐츠에서는 추가 클라이언트 작업이 그만한 가치가 있습니다. 총 생성 시간이 같더라도 첫 토큰 시간이 크게 줄어듭니다.
curl 관점
curl -N -s "$HIAPI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kimi-k3.1-pro-highspeed",
"messages": [{"role": "user", "content": "재시도에 관한 하이쿠를 써 주세요."}],
"stream": true
}'
-N은 curl의 출력 버퍼링을 비활성화하므로 이벤트가 전송되는 즉시 도착하는 것을 실제로 볼 수 있습니다. 각 줄이 data: 로 시작하고 JSON 조각을 담은 일련의 줄을 받게 됩니다. 마지막 이벤트는 data: [DONE]입니다. 이 센티널은 파싱할 JSON이 아니라 스트림 종료 표시로 취급하세요.
Python 클라이언트
import json
import requests
def stream_chat(user_message: str, timeout: float = 60.0) -> str:
payload = {
"model": MODEL,
"messages": [{"role": "user", "content": user_message}],
"stream": True,
}
pieces = []
with requests.post(
f"{BASE_URL}/chat/completions",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
stream=True,
timeout=timeout,
) as r:
r.raise_for_status()
for raw in r.iter_lines(decode_unicode=True):
if not raw or not raw.startswith("data: "):
continue
data = raw[len("data: "):].strip()
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0].get("delta", {})
text = delta.get("content")
if text:
pieces.append(text)
print(text, end="", flush=True)
return "".join(pieces)
스트리밍을 올바르게 유지하는 규칙
- 교체가 아니라 연결. 각 청크는 새 조각만 담습니다. 목록에 누적한 뒤 마지막에 한 번 join하세요. 루프에서 문자열에 덧붙이면 긴 출력에서 이차 복잡도가 됩니다.
- 누락된 콘텐츠에 대비. 일부 청크는 메타데이터만 담으므로
delta에content키가 없을 수 있습니다..get()을 사용하고 빈 값을 건너뛰세요. - 불완전한 줄 처리. 프레임 경계가 줄을 나눌 수 있습니다.
iter_lines가 이를 처리하지만, 원시 바이트 스트림을 직접 파싱한다면 개행 문자가 보일 때까지 버퍼링하세요. - 스트림에 맞는 타임아웃 설정. 전체 스트림은 짧은 요청 타임아웃을 합법적으로 초과할 수 있습니다. 타임아웃을 완전히 비활성화하지 말고 더 긴 읽기 타임아웃이나 청크별 읽기 기한을 사용하세요.
- 비스트리밍 경로 유지. 백그라운드 작업의 최종 텍스트만 필요할 때는
stream: false가 더 단순하고 추론 비용도 낮습니다. 스트리밍은 대화형 경로에 남겨 두세요.
오류 응답 해석 및 재시도 설계
실패가 일시적일 때만 재시도가 도움이 됩니다. 형식이 잘못된 요청을 맹목적으로 재시도하면 오류만 증폭됩니다. 유용한 구분은 코드에서 고쳐야 할 오류와 네트워크나 서버가 스스로 해결할 오류입니다.
상태 코드별 분류
재시도하지 말고 요청 수정:
- 400 Bad Request — JSON 형식 오류, 필수 필드 누락 또는 잘못된 매개변수 값입니다. 오류 메시지를 읽고 요청 페이로드를 고치며, 재발 방지를 위한 테스트를 추가하세요.
- 401 Unauthorized — 키가 없거나, 형식이 잘못되었거나, 폐기되었습니다.
Authorization헤더 형식과 환경 변수가 셸에만 있는 것이 아니라 실제 실행 프로세스에 설정되었는지 확인하세요. - 403 Forbidden — 키는 유효하지만 이 작업을 수행하거나 이 모델을 사용할 권한이 없습니다. 여기서의 재시도 루프는 순전히 노이즈입니다.
- 404 Not Found — 보통 경로가 틀렸거나 모델 식별자를 알 수 없습니다. 기본 URL과 정확한 모델 문자열을 확인하세요.
- 422 류 검증 오류 — 매개변수 타입은 맞지만 값이 허용되지 않습니다(예: 범위를 벗어난
temperature). 코드에서 값을 클램프하세요.
백오프와 함께 재시도:
- 429 Too Many Requests — 속도 제한을 초과했습니다. 백오프하고, 응답에 retry-after 힌트가 있으면 추측하지 말고 따르세요.
- 500 / 502 / 503 / 504 — 서버 측 또는 게이트웨이 장애입니다. 지수 백오프가 바로 여기서 쓰입니다.
- 연결 오류 및 타임아웃 — 응답이 완료되기 전에 소켓이 실패했습니다. 재시도하되, 작업이 안전하게 반복 가능할 때만 하세요.
제대로 동작하는 재시도 루프
import random
import time
import requests
RETRYABLE_STATUS = {429, 500, 502, 503, 504}
def post_with_retries(url, headers, payload, max_attempts=4, base_delay=1.0):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(url, headers=headers, json=payload, timeout=30.0)
except (requests.ConnectionError, requests.Timeout):
if attempt == max_attempts:
raise
else:
if r.status_code < 400:
return r.json()
if r.status_code not in RETRYABLE_STATUS:
raise RuntimeError(f"재시도 불가 {r.status_code}: {r.text[:200]}")
if attempt == max_attempts:
raise RuntimeError(f"재시도 소진, 마지막 {r.status_code}")
delay = base_delay * (2 ** (attempt - 1))
time.sleep(delay + random.uniform(0, 0.5))
raise RuntimeError("unreachable")
프로덕션에서 중요한 두 가지 세부 사항
- 지터는 선택 사항이 아닙니다. 이것이 없으면 동시에 속도 제한에 부딪힌 작업자 무리가 보조를 맞춰 재시도하며 스파이크를 다시 만들어냅니다. 위의 무작위 항목이 이들을 분산시킵니다.
- 시도 횟수뿐 아니라 총 시간도 제한하세요. 네 번의 지수 백오프 시도는 요청 기한을 초과할 수 있습니다. 최악의 경우가 호출자의 예산 안에 남도록 시도 횟수를 제한하고, 남은 시간을 다음 시도의 타임아웃으로 전달하세요.
사용자에게 이미 보낸 텍스트를 어떻게 처리할지 결정하지 않았다면 부분 실패 시 스트리밍 요청을 재시도하지 마세요. 일반적인 패턴은 아직 아무것도 표시하지 않았을 때만 재시도하고, 그렇지 않으면 잘림을 노출하는 것입니다.
출시 전 체크리스트
이 코드가 중요한 워크로드가 되기 전에 짧은 체크리스트를 실행하세요.
- 모든 곳에 타임아웃. 모든 요청에 명시적인 연결/읽기 타임아웃이 있고, 그 값은 예제에서 복사한 것이 아니라 지연 예산에서 나옵니다.
- 기밀은 저장소 밖에. API 키는 환경이나 비밀 관리자에서 오고 절대 로그에 기록되지 않습니다. 모든 요청 로거에서 헤더를 제거하세요.
- 모델 이름은 한곳에.
kimi-k3.1-pro-highspeed가 단일 상수로 나타나므로 검색 후 바꾸기 없이 교체하거나 A/B 테스트할 수 있습니다. - 오류는 분류되고, 삼켜지지 않습니다. 재시도 가능 경로와 불가능 경로가 코드에서 명확히 구분되고, 백오프에 지터가 포함되며, 시도 횟수에 상한이 있습니다.
- 사용량 기록. 각 응답이 반환한 토큰 사용량을 지연 시간, 상태와 함께 기록하세요. 토큰 기반 과금에서는 프롬프트가 조용히 너무 커지고 있다는 조기 경고입니다.
- 스트리밍 경로는 실제로 테스트됨. 같은 프롬프트에서 연결된 출력이 비스트리밍 출력과 같고, 스트림 중간 단절이 UI를 깨진 상태로 남기지 않는지 검증하세요.
- 비용은 설계로 통제. 항상
max_tokens를 설정하고, 대화 기록을 잘라내고, 긴 문서는 컨텍스트에 넣기 전에 요약하세요. 이 세 가지 레버가 지출을 가치에 비례하게 만듭니다.
이를 갖추면 curl 개념 증명에서 프로덕션 호출자로 넘어가는 일은 주로 구성 작업입니다. 비스트리밍 함수로 시작하고, 대화형 경로가 생긴 뒤에 스트리밍을 추가하며, 예방할 수 없는 실패는 재시도 래퍼가 흡수하게 하세요.