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

무엇을 만들게 될까요

kimi-k3는 추론 능력을 갖춘 대화 모델로, 표준 OpenAI 호환 /v1/chat/completions 엔드포인트를 통해 hiapi에서 사용할 수 있습니다. 비동기 작업을 폴링할 필요도, 이미지를 업로드할 필요도 없습니다. 이 가이드는 curl과 Python으로 처음부터 실행 가능한 호출을 완성하고, 그다음 프로덕션 환경에서 흔히 걸려 넘어지는 두 가지—추론 token이 max_tokens 예산을 잡아먹는 문제, 그리고 스트리밍 출력—을 설명합니다.

사전 준비: hiapi API 키 하나. 아직 없다면 콘솔에서 받으세요. 아래 모든 요청은 Authorization: Bearer sk-<your-key>로 인증합니다.

최소 실행 예제

kimi-k3는 텍스트 모델이므로, hiapi가 이미지/비디오 모델에 사용하는 /v1/tasks 태스크 큐를 거치지 않습니다. 이는 한 번의 직접적이고 동기적인 대화 완성 호출입니다.

curl

curl https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
    ],
    "max_tokens": 300
  }'

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [
            {"role": "user", "content": "Explain what an API rate limit is in two sentences."}
        ],
        "max_tokens": 300,
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["choices"][0]["message"]["content"])

성공 응답은 다음과 같습니다:

{
  "id": "chatcmpl-fb762e7481bd4442abb1d8ed3892b4f5",
  "model": "FW-Kimi-K3",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need answer user: \"Reply with exactly the word OK.\" ..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 95,
    "completion_tokens": 52,
    "total_tokens": 147,
    "completion_tokens_details": {"reasoning_tokens": 38}
  }
}

최종 답변은 choices[0].message.content에 있습니다. 요청의 모델 ID는 순수 ID인 kimi-k3입니다. hiapi가 내부적으로 매핑하며(응답 본문의 model 필드에는 FW-Kimi-K3 같은 내부 레이블이 에코되는데, 이는 정상 동작입니다).

유일한 함정: 추론 token과 max_tokens

kimi-k3는 추론 모델로서, 최종 content를 생성하기 전에 사고 연쇄를 message.reasoning_content에 기록하며, 둘은 동일한 max_tokens 예산을 공유합니다. max_tokens를 너무 낮게 설정하면 모델이 예산 전체를 추론에 소진하고 finish_reason: "length"를 반환하면서 content 필드는 비어 있을 수 있습니다:

{
  "choices": [{
    "message": {"content": "", "reasoning_content": "The user is asking me to say \"OK\""},
    "finish_reason": "length"
  }]
}

이것은 버그가 아닙니다—추론 과정이 최종 답변에 도달하기 전에 공간을 다 써버린 것뿐입니다. 두 가지 처리 방법이 있습니다:

• 충분한 여유를 주세요. 짧은 사실적 답변의 경우 200–300의 max_tokens면 보통 추론과 답변을 모두 커버합니다. 더 긴 생성 내용에는 그에 맞게 예산을 높이세요.
• finish_reason을 확인하세요. "length"가 반환되고 content가 비어 있다면, max_tokens를 높여 다시 시도하고 빈 문자열을 최종 답변으로 취급하지 마세요.

스트리밍 출력

"stream": true를 설정하면 전체 응답을 기다리지 않고 서버 전송 이벤트(SSE)를 받을 수 있습니다. 데이터 청크는 먼저 증분 delta.reasoning_content를 담고, 모델이 최종 답변을 쓰기 시작하면 delta.content를 담습니다:

import requests

with requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-<your-key>",
        "Content-Type": "application/json",
    },
    json={
        "model": "kimi-k3",
        "messages": [{"role": "user", "content": "Count to 3."}],
        "max_tokens": 200,
        "stream": True,
    },
    stream=True,
    timeout=60,
) as resp:
    for line in resp.iter_lines():
        if line and line.startswith(b"data: ") and line != b"data: [DONE]":
            print(line.decode("utf-8"))

채팅 인터페이스를 만든다면 delta.content만 스트리밍 렌더링하세요. 대부분의 앱은 delta.reasoning_content를 "생각 중" 토글 뒤에 숨기거나 접어서 보여주며, 인라인으로 표시하지 않습니다.

프로덕션 환경 주의사항

• 오류 처리. 유효하지 않거나 누락된 키는 HTTP 401과 구조화된 응답 본문을 반환합니다:

  {"error": {"code": "permission_denied", "message": "This API key is invalid...", "request_id": "...", "type": "hiapi_error"}}
  

  request_id를 기록하세요—티켓을 제출할 경우 지원팀이 필요로 합니다.
• 재시도. 대화 완성은 동기식이므로 폴링할 태스크 ID도, 등록할 콜백도 없습니다(그 패턴은 hiapi의 비동기 이미지/비디오 모델에 적용되며 텍스트에는 적용되지 않습니다). 타임아웃이나 5xx가 발생하면 요청을 그대로 재시도하면 됩니다. 서버에 대기 중인 작업이 없으므로 일반적인 멱등 GET류 재시도로 취급할 수 있습니다.
• 과금. kimi-k3는 플랫폼의 다른 텍스트 모델과 마찬가지로 token 단위로 과금됩니다—규모화 비용을 추정하기 전에 가격 페이지에서 현재 요율을 확인하세요. 추론 token도 완성 token에 포함되기 때문입니다.

자주 묻는 질문

kimi-k3는 스트리밍 출력을 지원하나요? 지원합니다—"stream": true를 전달하고 위에 표시된 대로 text/event-stream 응답을 읽으세요.

왜 응답의 content가 비어 있나요? finish_reason이 거의 확실히 "length"입니다—모델이 최종 답변에 도달하기 전에 max_tokens 예산 전체를 reasoning_content에 소진했습니다. max_tokens를 높이고 다시 시도하세요.

kimi-k3에 hiapi의 /v1/tasks 엔드포인트가 필요한가요? 아니요. /v1/tasks는 비동기 이미지, 비디오, 음악 생성 모델에 사용됩니다. kimi-k3는 동기 텍스트 모델로, 표준 /v1/chat/completions 엔드포인트를 통해 제공됩니다.

네이티브 requests 대신 OpenAI Python SDK를 사용할 수 있나요? 네—SDK의 base_url을 https://api.hiapi.ai/v1로 지정하고 hiapi 키를 API 키로 전달하세요. 요청/응답 구조가 OpenAI와 호환됩니다.

요청에 어떤 모델 ID를 전달해야 하나요? 순수 ID인 kimi-k3입니다. 응답 본문의 model 필드에 FW-Kimi-K3 같은 내부 레이블이 에코되는 것을 보게 되는데, 이는 정상 동작이며 과금이나 동작에 영향을 주지 않습니다.