教程

如何通过 hiapi API 使用 deepseek-v4-flash-vision-exp：curl、Python 与一个可用的请求

2026年11月3日

deepseek-v4-flash-vision-exp 是 hiapi 上一个具备推理能力的文本与视觉模型，可通过标准的 OpenAI 兼容端点访问：POST /v1/chat/completions。它能同时读取图像和文本，支持 JSON 模式和函数/工具调用，并支持流式输出——所有这些都通过与其他任何 hiapi 聊天模型相同的请求结构完成。本指南将带你走一遍可用的请求、一个容易让人踩坑的行为（模型会先推理再作答，而推理过程会占用你的 token 预算），以及在上线前值得了解的生产实践。

你将构建什么

一个脚本，向 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 预算——在这个简单示例中，37 个 completion token 中有 34 个用于推理，模型才写出 "OK"。

这就是那个坑：把 max_tokens 设置得太低，模型可能会把整个预算都花在推理上，导致 content 为 null，且 finish_reason 为 "length"。同样的请求在 max_tokens: 10 时返回 content: null——模型在达到上限时仍在思考中。给这个模型留足空间：简短回答至少 150–300 个 token，需要真正推理深度的内容则要更多。

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）才是供机器消费的。
视觉输入接受公开 URL，而不是内联 base64。image_url.url 需要能被 hiapi 的服务器抓取；在发送请求前，请自行托管图像或使用你已控制的 URL。

常见问题

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（如果问题持续存在）。

要点总结

使用裸模型 ID "deepseek-v4-flash-vision-exp" 调用 POST /v1/chat/completions——没有单独的视觉或工具端点。
慷慨地设置 max_tokens（150-300+）：reasoning_content 与 content 消耗同一预算，上限太低会返回 content: null 和 finish_reason "length"。
视觉输入放入 content 数组中：{"type":"image_url","image_url":{"url":...}} 与文本分段并列，使用任何公开图像 URL。
response_format: {"type":"json_object"} 会在 message.content 中返回可解析的 JSON；对于结构化输出请忽略 reasoning_content。
tools 数组会触发 finish_reason: "tool_calls"，并返回标准 OpenAI 形态的 tool_calls 数组。
认证失败返回 HTTP 401，包含 code: "permission_denied" 以及可供支持使用的 request_id。