hiapi API로 deepseek-v4.1-flash를 사용하는 방법: curl, Python 및 사용 가능한 요청 예시

deepseek-v4.1-flash는 hiapi 통합 API를 통해 호출할 수 있는 빠르고 저렴한 추론 모델입니다. 현재 모델 페이지에서 프리뷰(Preview)로 표시되어 있으며, 이는 기반 빌드가 교체될 수 있지만 공개 모델 ID(deepseek-v4.1-flash)는 안정적으로 유지된다는 뜻입니다. 교체가 발생해도 코드를 수정할 필요가 없습니다. 이 가이드는 실제로 동작하는 요청을 보여줍니다: 올바른 엔드포인트, 올바른 필드, 올바른 인증 헤더.

사전 요구 사항

• hiapi API 키(sk-...)가 필요합니다. hiapi 콘솔에서 발급받은 후 내보내세요:

export HIAPI_API_KEY="sk-your-key-here"

• 모든 HTTP 클라이언트를 사용할 수 있습니다. 아래 예시는 curl과 Python requests를 사용하며, 공식 OpenAI SDK 사용 방법도 함께 설명합니다.

최소 동작 예시

hiapi는 두 개의 텍스트 엔드포인트를 제공합니다. /v1/responses는 표준 권장 엔드포인트(OpenAI Responses API 형태, 의미론적 SSE 이벤트)입니다. /v1/chat/completions는 구버전 호환 엔드포인트(OpenAI Chat Completions 형태)로, 기존 Chat Completions 통합을 이식할 때만 사용하세요. 이 가이드는 /v1/responses를 사용합니다.

curl

curl https://api.hiapi.ai/v1/responses \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "input": [
      {"role": "user", "content": "Explain what a hash map is in two sentences."}
    ]
  }'

성공 응답은 모델의 답변이 담긴 output 배열과 usage 블록을 반환합니다:

{
  "id": "resp_...",
  "model": "deepseek-v4.1-flash-expires-on-0910",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "A hash map stores key-value pairs..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 42,
    "total_tokens": 56,
    "output_tokens_details": {"reasoning_tokens": 0}
  }
}

응답의 model 필드가 deepseek-v4.1-flash-expires-on-0910으로 표시된 점에 주목하세요. 이는 현재 이 프리뷰 모델을 서비스하는 고정된 내부 빌드입니다. 이는 hiapi에서 프리뷰 모델의 예상된 동작이며, 모델이 곧 종료된다는 신호가 아닙니다. 계속해서 순수한 deepseek-v4.1-flash ID로 요청하면 hiapi가 자동으로 현재 빌드로 라우팅합니다.

Python

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [
            {"role": "user", "content": "Explain what a hash map is in two sentences."}
        ],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()
print(data["output"][0]["content"][0]["text"])
print(data["usage"])

OpenAI SDK로 전환

hiapi의 /v1/responses와 /v1/chat/completions는 공식 OpenAI SDK와 호환됩니다. base URL만 hiapi로 지정하고 모델 ID는 순수 이름을 유지하세요:

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HIAPI_API_KEY"],
    base_url="https://api.hiapi.ai/v1",
)
resp = client.responses.create(
    model="deepseek-v4.1-flash",
    input=[{"role": "user", "content": "Explain what a hash map is in two sentences."}],
)
print(resp.output[0].content[0].text)

프로덕션 환경 실무

요청은 무상태입니다 — 전체 대화를 재전송해야 합니다

hiapi는 이 모델에 대해 서버 측 대화 상태를 보존하지 않습니다. 모든 요청은 input에 전체 메시지 기록을 포함해야 합니다. store, previous_response_id, conversation, background, context_management를 보내지 마세요. 이들은 지원되지 않으며 무시되거나 거부됩니다. 멀티턴 대화에서는 매번 새로운 user/assistant 메시지를 input 배열에 직접 추가하고, 요청할 때마다 전체 배열을 전송하세요.

history = [{"role": "user", "content": "What's a hash map?"}]
# ... call, get a reply, then append it and the next question ...
history.append({"role": "assistant", "content": "<model's previous reply>"})
history.append({"role": "user", "content": "How is that different from a hash set?"})

추론 강도

deepseek-v4.1-flash는 답변 전에 내부 추론을 얼마나 수행할지 제어하는 reasoning 객체를 받습니다. 이 모델의 effort 열거형은 none | high | max입니다. hiapi의 일부 다른 추론 모델이 사용하는 low/medium/high 단계와 다르므로 그대로 적용할 수 있다고 가정하지 마세요.

{
  "model": "deepseek-v4.1-flash",
  "input": [{"role": "user", "content": "Prove that the square root of 2 is irrational."}],
  "reasoning": {"effort": "high"}
}

추론 토큰은 출력 토큰으로 과금되며 usage.output_tokens_details.reasoning_tokens에 별도로 보고됩니다. 따라서 high/max 강도의 요청은 보이는 답변 길이가 같아도 none보다 눈에 띄게 비쌀 수 있습니다. 프로덕션 트래픽의 기본 강도를 설정하기 전에 요금 페이지에서 현재 토큰당 요금을 확인하세요.

스트리밍

"stream": true를 전달하면 단일 JSON 덩어리 대신 Server-Sent Events를 받습니다. /v1/responses는 Chat-Completions 스타일의 [DONE] 마커로 감싼 원시 텍스트 델타가 아니라 의미론적 이벤트를 스트리밍합니다. 정상적으로 완료되는 이벤트 순서는 다음과 같습니다:

response.created
response.in_progress
response.output_item.added
response.content_part.added
response.output_text.delta   (repeated, one per chunk of text)
response.output_text.done
response.content_part.done
response.output_item.done
response.completed

response.completed를 성공 종료 이벤트로 처리하세요. response.incomplete(예: 토큰/길이 제한 도달)와 response.failed(서버 오류)도 종료 상태로 처리해야 합니다. 모든 스트림이 response.completed로 끝난다고 가정하지 마세요.

import json
import requests

with requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "input": [{"role": "user", "content": "Count to 5."}],
        "stream": True,
    },
    stream=True,
    timeout=60,
) as r:
    for line in r.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":
            print(event["delta"], end="", flush=True)
        elif event.get("type") in ("response.completed", "response.incomplete", "response.failed"):
            break

오류 처리

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

{"error": {"code": "permission_denied", "message": "..."}}

resp.status_code를 확인하고 error.code로 분기 처리하세요. 메시지 문자열은 예고 없이 문구가 변경될 수 있으므로 파싱하지 마세요.

관련 문서

• deepseek-v4.1-flash 모델 페이지
• /v1/responses 참조
• /v1/chat/completions 참조
• 인증
• 요금

자주 묻는 질문

deepseek-v4.1-flash는 프로덕션용인가요, 아니면 테스트 전용인가요? 프리뷰로 표시되어 있으며, hiapi에서 이는 모델이 라이브 상태이고 정상적으로 호출 가능하지만 기반 빌드는 hiapi의 계획에 따라 교체될 수 있음을 의미합니다. 교체 시 공개 모델 ID는 변경되지 않으므로 코드는 수정 없이 계속 작동합니다. 프리뷰가 아닌 정식 보장이 필요하다면 모델 목록에서 비프리뷰 DeepSeek v4 변형을 확인하세요.

왜 응답의 모델 이름이 요청한 것과 다른가요? 응답의 model 필드에 deepseek-v4.1-flash-expires-on-0910 같은 값이 표시됩니다. 이는 현재 deepseek-v4.1-flash ID로 요청을 서비스하는 특정 고정 빌드로, 프리뷰 모델의 예상된 동작이며 오류가 아닙니다.

/v1/responses 대신 /v1/chat/completions를 사용할 수 있나요? 네, hiapi는 이 모델에 대해 둘 다 지원합니다. /v1/chat/completions는 /v1/responses의 input/output 형태가 아니라 OpenAI Chat Completions의 요청/응답 형태(messages 배열, choices[0].message.content)를 사용합니다. 기존 통합에 맞는 것을 선택하세요. 새 통합은 기본적으로 /v1/responses를 사용해야 합니다.

hiapi가 대화 기록을 저장해서 최신 메시지만 보내면 되나요? 아니요. 이 모델에는 previous_response_id나 서버 측 대화 상태가 없습니다. 매 요청마다 input에 전체 메시지 기록을 전송해야 합니다.

reasoning.effort: "none"은 실제로 무엇을 건너뛰나요? 모델의 내부 추론 과정을 완전히 건너뛰고 바로 답변합니다. 다단계 추론이 유리한 작업(수학, 다중 제약 논리)에는 "high" 또는 "max"를 사용하세요. 강도가 높을수록 출력 토큰 사용량과 지연 시간도 비례하여 증가합니다.

스트리밍 요청과 비스트리밍 요청에 별도의 API 키가 필요한가요? 아니요. 동일한 Authorization: Bearer sk-... 키가 둘 다에 적용됩니다. 스트리밍은 전적으로 요청 본문의 "stream": true 필드로 제어됩니다.