hiapi API로 deepseek-v4-flash-vision-exp 사용하는 방법: curl, Python 그리고 실제로 동작하는 요청

deepseek-v4-flash-vision-exp는 hiapi에서 추론 기능을 갖춘 텍스트 및 비전 모델이며, 표준 OpenAI 호환 엔드포인트인 POST /v1/chat/completions를 통해 접근할 수 있습니다. 이 모델은 이미지와 텍스트를 동시에 읽을 수 있고, JSON 모드와 함수/도구 호출을 지원하며, 스트리밍 출력도 지원합니다. 이 모든 것은 다른 hiapi 채팅 모델과 동일한 요청 구조로 이루어집니다. 이 가이드에서는 실제로 동작하는 요청, 사람들이 쉽게 빠지는 함정 하나(모델이 먼저 추론한 뒤 답하며, 그 추론 과정이 토큰 예산을 소모한다는 점), 그리고 출시 전에 알아두면 좋은 프로덕션 실무를 살펴봅니다.

무엇을 만들게 되나요

deepseek-v4-flash-vision-exp에 프롬프트를 보내고——선택적으로 이미지를 첨부하여——내부 추론 흔적이 아닌 실제 답변을 읽어오는 스크립트입니다.

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

최소 동작 예제

curl

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      { "role": "user", "content": "Say OK and nothing else." }
    ],
    "max_tokens": 200
  }'

간략화한 응답은 다음과 같습니다:

{
  "choices": [
    {
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "OK",
        "reasoning_content": "We need to respond exactly \"OK\" and nothing else. ..."
      }
    }
  ],
  "usage": {
    "completion_tokens": 37,
    "completion_tokens_details": { "reasoning_tokens": 34 },
    "prompt_tokens": 89,
    "total_tokens": 126
  }
}

여기서 두 필드가 중요합니다: message.content는 실제 답변이고, message.reasoning_content는 모델이 그 답변을 확정하기 전의 내부 사고 사슬입니다. usage.completion_tokens_details.reasoning_tokens는 추론 과정이 max_tokens 예산을 얼마나 소모했는지 알려줍니다. 이 간단한 예제에서는 completion 토큰 37개 중 34개가 추론에 쓰였고, 그 후에야 모델이 "OK"를 작성했습니다.

바로 그 함정입니다: max_tokens를 너무 낮게 설정하면 모델이 예산 전체를 추론에 써버려 content가 null이 되고 finish_reason이 "length"가 될 수 있습니다. 같은 요청을 max_tokens: 10으로 보내면 content: null이 반환됩니다——모델이 상한에 도달했을 때 여전히 생각 중이었던 것입니다. 이 모델에는 충분한 여유를 두세요: 짧은 답변에는 최소 150–300 토큰, 진정한 추론 깊이가 필요한 내용에는 그보다 더 많이 필요합니다.

Python

import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4-flash-vision-exp",
        "messages": [
            {"role": "user", "content": "Say OK and nothing else."},
        ],
        "max_tokens": 200,
    },
    timeout=60,
)
resp.raise_for_status()
message = resp.json()["choices"][0]["message"]
print(message["content"])

비전 입력

content를 타입이 지정된 세그먼트 배열로 설정하면 텍스트 옆에 이미지를 전달할 수 있습니다——image_url은 공개적으로 접근 가능한 이미지 URL이면 무엇이든 받습니다:

curl -s -X POST "https://api.hiapi.ai/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-vision-exp",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What color is the dominant background color of this image? One word." },
          { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
        ]
      }
    ],
    "max_tokens": 200
  }'

실제 테스트 이미지에 대해 모델은 "Beige"를 반환했고, reasoning_content는 한 단어 답변을 내놓기 전에 시각적 묘사를 먼저 거쳤음을 보여주었습니다——텍스트 전용 요청과 동일한 추론 후 답변 패턴이되, 근거가 이미지인 경우입니다.

JSON 모드와 도구 호출

구조화된 JSON 출력——response_format: {"type": "json_object"}를 추가하고 프롬프트에서 JSON을 언급하세요:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "Return a JSON object with keys name and age for a fictional person." }
  ],
  "response_format": { "type": "json_object" },
  "max_tokens": 300
}

message.content는 파싱 가능한 JSON 문자열로 반환되며({"name": "Alex Doe", "age": 30}), reasoning_content는 여전히 모델의 초안 내용을 담고 있습니다——content만 파싱하고, reasoning_content는 절대 파싱하지 마세요.

함수/도구 호출——표준 OpenAI 스타일의 tools 배열을 전달하세요:

{
  "model": "deepseek-v4-flash-vision-exp",
  "messages": [
    { "role": "user", "content": "What is the weather in Tokyo right now? Use the get_weather tool." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }
  ],
  "max_tokens": 300
}

모델은 finish_reason: "tool_calls"와 tool_calls 배열로 응답합니다(function.name, JSON 문자열로 된 function.arguments, 그리고 후속 턴에서 다시 전달할 call_id 포함)——표준 OpenAI 함수 호출 루프가 수정 없이 동작합니다.

프로덕션 고려사항

• 답변뿐 아니라 추론까지 고려하여 max_tokens 예산을 확보하세요. 이것은 추론 모델입니다——모든 응답은 최종 content 이전에 reasoning_content 과정을 포함하며, 둘 다 같은 max_tokens 풀에서 소모됩니다. 초기 테스트에서 usage.completion_tokens_details.reasoning_tokens를 확인하여 프롬프트에 맞는 안전한 상한을 보정하고, 항상 finish_reason을 확인하세요——"length"이면서 content가 null이라면 진정한 답변을 얻은 것이 아니라 사고 도중 잘린 것입니다.
• 스트리밍 출력은 stream: true로 동작합니다. hiapi의 일부 추론 모델처럼 스트리밍을 강제하는 것과 달리, 이 모델은 두 모드를 모두 지원합니다. 스트리밍 모드에서 reasoning_content와 content는 동일한 chunk 스트림에서 독립적인 delta 필드로 도착합니다——'생각'과 '답변'을 서로 다른 UI 상태로 표시하려면 각각 버퍼링하세요.
• 인증 실패는 명확하게 반환됩니다. 잘못되었거나 폐기된 키는 HTTP 401을 반환하며, 오류 본문에는 "code": "permission_denied"와 request_id가 포함됩니다. 메시지 문자열을 매칭하는 대신 code 필드에 따라 분기 처리하고, 지원팀에 문의할 때는 request_id를 첨부하세요.
• reasoning_content를 최종 사용자에게 답변으로 보여주지 마세요. 그것은 구조화되지 않은 초안 내용이지 최종 응답이 아닙니다——특히 JSON 모드나 도구 호출에서는 content(또는 tool_calls)만이 기계가 소비할 대상입니다.
• 비전 입력은 인라인 base64가 아닌 공개 URL을 받습니다. image_url.url은 hiapi 서버가 가져올 수 있어야 합니다. 요청을 보내기 전에 이미지를 직접 호스팅하거나 이미 제어하고 있는 URL을 사용하세요.

관련 읽기

• deepseek-v4-flash-vision-exp 모델 페이지——전체 파라미터 참조 및 실시간 가격
• hiapi API 문서——인증, 다른 모델 계열 및 전체 엔드포인트 목록
• hiapi 가격——deepseek-v4-flash-vision-exp 및 기타 모든 모델의 토큰당 요율
• gpt-6-astra API 가이드——hiapi의 두 번째 추론 모델로, 통합 형태가 다르며(스트리밍 전용, Responses API) 비교 참고할 만합니다

자주 묻는 질문

deepseek-v4-flash-vision-exp는 비전 입력을 지원하나요? 지원합니다. 배열 형태의 content에 text 세그먼트 하나와 하나 이상의 image_url 세그먼트를 담아 보내세요. 각 세그먼트는 공개적으로 접근 가능한 이미지 URL을 가리킵니다. 모델은 텍스트와 마찬가지로 이미지에 대해 먼저 추론한 뒤 답변합니다.

왜 응답에서 message.content가 null인가요? max_tokens가 너무 낮아서 모델의 추론 과정이 답변을 작성하기 전에 예산 전체를 소진한 것입니다. finish_reason을 확인하세요——"length"이면서 content: null이면 이 경우입니다. max_tokens를 늘리고 다시 시도하세요.

JSON 모드를 지원하나요? 지원합니다. response_format: {"type": "json_object"}를 통해 가능합니다. JSON은 문자열 형태로 message.content에 담기며 직접 파싱해야 합니다. reasoning_content는 구조화된 출력에 속하지 않으므로 이 시나리오에서는 무시해야 합니다.

함수/도구 호출을 지원하나요? 지원합니다. 표준 OpenAI tools 배열 형식을 사용합니다. 도구를 트리거하는 응답은 finish_reason: "tool_calls"와 함수 이름 및 인자를 담은 tool_calls 배열을 반환합니다.

응답을 스트리밍으로 받을 수 있나요? 가능합니다——"stream": true를 설정하고 chat.completion.chunk 이벤트를 소비하세요. content와 reasoning_content 모두 동일한 chunk 내의 독립적인 delta 필드로 스트리밍됩니다.

인증 오류는 어떤 모습인가요? HTTP 401이며, JSON 응답 본문에 "type": "hiapi_error", "code": "permission_denied", 사람이 읽을 수 있는 message, 그리고 문제가 지속될 경우 지원팀에 전달할 수 있는 request_id가 포함됩니다.