HiAPI
Zh
博客

教程

如何通过 hiapi API 使用 deepseek-v4.1-flash：curl、Python 及可用的请求示例

2026年11月3日
如何通过 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"}
}

推理 token 按输出 token 计费，并单独报告在 usage.output_tokens_details.reasoning_tokens 中，因此 high/max 强度的请求即使可见答案长度相同，也可能比 none 明显更贵。在为生产流量设置默认强度之前，请先在定价页面查看当前的每 token 费率。

流式传输

传入 "stream": true 可获得 Server-Sent Events 而非单个 JSON 数据块。/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（例如触及 token/长度限制）和 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 是可用于生产，还是仅用于测试？ 它标记为预览版，在 hiapi 上这意味着模型已上线且可正常调用，但底层构建可能按 hiapi 的安排轮换。轮换时公开模型 ID 不会变化——你的代码无需修改即可继续工作。如果你需要非预览版的正式承诺，请查看模型列表中非预览版的 DeepSeek v4 变体。

为什么响应显示的模型名称与我请求的不同？ 你会在响应的 model 字段中看到类似 deepseek-v4.1-flash-expires-on-0910 的值。那是当前在 deepseek-v4.1-flash ID 下为你的请求提供服务的特定固定构建——这是预览版模型的预期行为，不是错误。

我可以使用 /v1/chat/completions 代替 /v1/responses 吗？ 可以，hiapi 为该模型同时支持两者。/v1/chat/completions 使用 OpenAI Chat Completions 的请求/响应形态（messages 数组、choices[0].message.content），而非 /v1/responses 的 input/output 形态。选择与你现有集成匹配的那个；新集成应默认使用 /v1/responses。

hiapi 会存储我的对话历史，以便我只发送最新消息吗？ 不会。该模型没有 previous_response_id 或服务端对话状态——每次请求都要在 input 中发送完整的消息历史。

reasoning.effort: "none" 实际跳过了什么？ 它完全跳过模型的内部推理过程，直接作答。对于受益于多步推理的任务（数学、多约束逻辑），请使用 "high" 或 "max"；强度越高，输出 token 用量和延迟也会相应增加。

流式请求和非流式请求需要单独的 API 密钥吗？ 不需要——同一个 Authorization: Bearer sk-... 密钥对两者都适用。流式传输完全由请求体中的 "stream": true 字段控制。

标签deepseekapi-guideTutorial

相关文章

查看全部文章 →

立即开始构建持久 AI 产物

获取 API 密钥，通过一个基于任务（task）的 API 调用图像、视频和音频模型。

阅读 API 文档