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
  }
}

ここで重要なフィールドは 2 つあります。message.content が実際の回答であり、message.reasoning_content はモデルがその回答を確定する前の内部思考連鎖です。usage.completion_tokens_details.reasoning_tokens は、推論プロセスが max_tokens 予算のうちどれだけを消費したかを示します。この単純な例では、37 個の completion トークンのうち 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 では 1 語の回答を出す前に視覚的な描写を一通り行っていたことが示されました。テキストのみのリクエストと同じ「推論してから回答」のパターンで、画像に基づいているだけです。

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）のみです。
• ビジョン入力は公開 URL を受け付け、インライン base64 は受け付けません。image_url.url は hiapi のサーバーが取得できる必要があります。リクエストを送信する前に、画像を自前でホストするか、自分が管理する URL を使用してください。

関連記事

• deepseek-v4-flash-vision-exp モデルページ：完全なパラメータリファレンスとリアルタイム価格
• hiapi API ドキュメント：認証、その他のモデルシリーズ、完全なエンドポイント一覧
• hiapi 価格：deepseek-v4-flash-vision-exp およびその他すべてのモデルのトークン単位の料金
• gpt-6-astra API ガイド：hiapi 上の 2 つ目の推論モデルで、異なる（ストリーミング専用、Responses API）統合形態を持ち、比較参考に値します

よくある質問

deepseek-v4-flash-vision-exp はビジョン入力をサポートしていますか？ はい。配列形式の content に text セグメントと 1 つ以上の image_url セグメントを含めて送信します。各 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 が含まれます。