EntHub AI 平台 API 接入文档

接入前准备

缺少 API Key，或应用未启用目标模型时，后续请求将失败。

1在控制台完成配置

请按下列顺序完成配置后再发起请求。

2首次文本调用

建议先完成文本对话路径验证，再扩展至图片、视频等协议。

请求接口

请求体字段

请求示例

将示例中的 API Key 与 model 替换为实际值后，在终端执行：

curl -X POST "https://api.lingfengtoken.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "你好，请用一句话介绍你自己"}],
    "stream": false
  }'

成功与常见错误

OpenAI 官方 SDK 配置

3流式响应

建议首次调用使用 stream: false；验证通过后再启用流式。流式响应以分片数据返回，结束标记通常为 data: [DONE]。

curl -N -X POST "https://api.lingfengtoken.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "hi"}],
    "stream": true
  }'

4按场景选择协议

文本路径验证通过后再扩展。不同模型族对应不同路径；路径选择错误是常见失败原因。

curl -X POST "https://api.lingfengtoken.com/v1/responses" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-codex",
    "input": "ping",
    "max_output_tokens": 64
  }'

curl -X POST "https://api.lingfengtoken.com/v1/images/generations" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1",
    "prompt": "a simple red apple",
    "size": "1024x1024"
  }'

curl -X POST "https://lingfengtoken.com/api/doubao/v1/images/generations" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-4-0",
    "prompt": "a simple red apple",
    "size": "1024x1024",
    "response_format": "url",
    "watermark": false
  }'

curl -X POST "https://lingfengtoken.com/api/qwen/api/v1/services/aigc/image-generation/generation" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-glb",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [{"text": "a simple red apple"}]
        }
      ]
    },
    "parameters": { "size": "1024*1024" }
  }'

curl -X POST "https://lingfengtoken.com/api/v1/kling/text-to-video/submit" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "Model": "kling-v2-5-turbo",
    "Prompt": "a cat walking on the street",
    "Duration": "5"
  }'

curl -X POST "https://lingfengtoken.com/api/gemini/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Generate a tiny solid red square icon, minimal"}]
      }
    ]
  }'

文本模能力总表（缓存 / 推理 / 工具）

先查阅本表再阅读专节。Claude / GPT 见「提示缓存」「推理与工具」；通义 / DeepSeek / Kimi / Gemini 见对应品牌专节。

清单来自模型目录中的文本对话模（已排除出图、视频、向量等）。推理/工具列优先看目录 Thinking、Function Calling；目录可能漏标，「否」不等于原厂一定不支持。是否对本企业开通，以控制台模型权限为准。

「说明覆盖」：已有专节 = Claude/GPT；品牌专节 = 通义/DeepSeek/Kimi/Gemini；仅总表 = 尚未写协议。缓存形态不是简单「有/无」——禁止把 Claude / GPT-5.6 字段抄到其它品牌。

• 请勿将 Claude 的 cache_control、GPT-5.6 的 prompt_cache_options / prompt_cache_breakpoint，或 OpenAI 的 prompt_cache_key 套用到通义、豆包、DeepSeek、Gemini 等其它厂——字段不同义，可能导致 400 或静默不命中。
• 通义显式 cache_control 与 DeepSeek/Kimi「默认自动」不是同一套开关；DeepSeek/Kimi 一般不要为了「开缓存」去抄显式断点。
• 推理/工具列若与原厂不一致，以原厂为准，并反馈我们修正目录标签。

提示缓存（降低重复前缀费用）

长系统提示、知识库、工具说明等稳定前缀可写入提示缓存，后续同前缀请求按缓存输入计价并通常更快。模型族不同，协议不同——选错路径是「开了缓存却命中为 0」的最常见原因。下列覆盖模型目录中全部 Claude 与 GPT 文本模；其它品牌先看「文本模能力总表」。

清单对齐模型目录中的 Claude 与 GPT 文本模（不含 gpt-image-*）。须在应用模型权限中启用后方可调用。

不含出图模（gpt-image-*）。OpenAI o3/o4 等推理系不在本 GPT 表；若已开通，缓存协议以官方自动缓存说明为准。

协议对照

Claude 文本模（全量）

GPT 文本模（全量）

model 必须与应用「模型权限」中的 ID 完全一致。已验证表示该 ID 在本平台已复核写入/命中字段；其余按官方公开协议对接，以回包 usage 为准。

Claude：Messages + cache_control

• •完整 URL：https://lingfengtoken.com/api/claude/v1/messages
• •请求头：Authorization: Bearer sk-lf-…（Claude Code 亦可用 x-api-key）；anthropic-version: 2023-06-01
• •两种官方写法：请求顶层 cache_control（自动断点），或内容块上 cache_control（显式断点）；可组合，显式断点最多 4 个
• •type 仅支持 ephemeral；可选 ttl: "5m"（默认）或 "1h"
• •前缀长度须达到该模型最小可缓存 token（见上表；不足时官方静默不缓存、不报错）；首笔看 usage.cache_creation_input_tokens；同前缀后续看 usage.cache_read_input_tokens

curl -X POST "https://lingfengtoken.com/api/claude/v1/messages" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 64,
    "system": [
      {
        "type": "text",
        "text": "You are an analyst. Stable instructions stay identical across requests.",
        "cache_control": { "type": "ephemeral", "ttl": "5m" }
      },
      {
        "type": "text",
        "text": "REPLACE_WITH_LONG_STABLE_PREFIX_MEETING_MODEL_MINIMUM",
        "cache_control": { "type": "ephemeral", "ttl": "5m" }
      }
    ],
    "messages": [
      { "role": "user", "content": "Summarize the major themes in one sentence." }
    ]
  }'

GPT-5.6：Responses 显式提示缓存

• •适用：gpt-5.6-luna / gpt-5.6-sol / gpt-5.6-terra（目录别名；官方文档称 GPT-5.6 and later）
• •完整 URL：https://api.lingfengtoken.com/v1/responses（本平台现网勿用 Chat 测缓存；官方 Chat 亦声明支持，但本链路实测不记账）
• •官方支持 implicit 与 explicit；示例采用 explicit。显式模式须打 prompt_cache_breakpoint，否则不写也不读
• •建议设置稳定的 prompt_cache_key（官方：5.6 要用更可靠匹配时须带 key）；prompt_cache_options.ttl 仅支持 "30m"
• •前缀经断点 ≥ 1024 token；首笔看 input_tokens_details.cache_write_tokens；后续看 cached_tokens

curl -X POST "https://api.lingfengtoken.com/v1/responses" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "max_output_tokens": 16,
    "prompt_cache_key": "demo-shared-prefix-v1",
    "prompt_cache_options": { "mode": "explicit", "ttl": "30m" },
    "input": [
      {
        "role": "developer",
        "content": [
          {
            "type": "input_text",
            "text": "REPLACE_WITH_LONG_STABLE_PREFIX_AT_LEAST_1024_TOKENS",
            "prompt_cache_breakpoint": { "mode": "explicit" }
          }
        ]
      },
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "Reply with one word: ok" }
        ]
      }
    ]
  }'

GPT-5.5 及更早：自动提示缓存

• •适用：gpt-5.5 及更早 GPT 文本模（含 Codex / Pro / gpt-4.1* / gpt-chat-latest）
• •官方：更早代际为自动前缀缓存，不支持 prompt_cache_options / prompt_cache_breakpoint；发送后者可能 400
• •prompt_cache_key 为可选项（分组路由/对账），不是开缓存开关；不设 key 也可自动命中
• •prompt_cache_retention 为可选项：gpt-5.5 仅 "24h"；部分更早模支持 "in_memory" 或 "24h"（下划线，不是 in-memory）
• •官方 extended retention 明确支持范围含：gpt-5.5、gpt-5.4、gpt-5.2、gpt-5.1*、gpt-5、gpt-5-codex、gpt-4.1 等；mini/nano/部分变体以实际报错为准
• •Codex、*-pro 等无 Chat 通道的模型：调用与缓存观测都走 POST /v1/responses
• •成功看 usage 中的 cached_tokens；更早代际通常无独立 cache_write 计费字段

通义 / DeepSeek / Kimi：下列按原厂公开协议整理；是否对本企业开通以控制台为准，实调用字段以回包为准。

通义 Qwen：隐式 / 显式缓存

• •文本主路径：POST https://api.lingfengtoken.com/v1/chat/completions（部分模目录亦标 responses）
• •隐式缓存：默认可能生效，无保证命中；稳定长前缀放 messages 靠前
• •显式缓存：在要缓存的 content 块上加 "cache_control": {"type": "ephemeral"}；与隐式互斥
• •显式门槛：可缓存前缀通常 ≥ 1024 token；TTL 约 5 分钟，命中可续期；单请求断点不宜过多（原厂约最多 4）
• •Responses 会话缓存（原厂）：头 x-dashscope-session-cache: enable + previous_response_id——领风是否透传该头请以实调用为准
• •成功字段（原厂）：usage.prompt_tokens_details.cached_tokens；显式创建可见 cache_creation_input_tokens

curl -X POST "https://api.lingfengtoken.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus-cn",
    "max_tokens": 64,
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "REPLACE_WITH_STABLE_PREFIX_AT_LEAST_1024_TOKENS",
            "cache_control": { "type": "ephemeral" }
          }
        ]
      },
      { "role": "user", "content": "用一句话回复：ok" }
    ]
  }'

DeepSeek：默认磁盘前缀缓存

• •路径：POST https://api.lingfengtoken.com/v1/chat/completions
• •无需 cache_control / prompt_cache_*；不要套 Claude 或 GPT-5.6 显式字段
• •把稳定 system / 工具说明 / 知识前缀放在 messages 最前，变化内容放最后
• •成功字段（原厂）：usage.prompt_cache_hit_tokens、usage.prompt_cache_miss_tokens
• •首笔新前缀常 hit=0；同前缀后续才应出现 hit

curl -X POST "https://api.lingfengtoken.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash-cn",
    "max_tokens": 64,
    "messages": [
      { "role": "system", "content": "REPLACE_WITH_LONG_STABLE_SYSTEM_PREFIX" },
      { "role": "user", "content": "用一句话回复：ok" }
    ]
  }'

Kimi：默认自动前缀缓存

• •路径：POST https://api.lingfengtoken.com/v1/chat/completions
• •自动缓存；无需手动建 cache id；短前缀（原厂约 prompt < 256 token）可能不入缓存
• •知识 / system / tools 定义保持字节稳定；多轮只追加、不改历史
• •可选 prompt_cache_key（会话亲和）——以原厂与回包为准；不是「开缓存」开关
• •成功：看 usage 中与 cached / cache 相关字段（形态随模型版本可能为 cached_tokens）

Google Gemini 文本模：下列协议以领风现网实测为准；原厂另有 generateContent / cachedContents，但领风网关对文本模另有限制，见下。

Gemini：Chat 路径看 cached_tokens；显式 cachedContents 未开放

• •文本主路径：POST https://api.lingfengtoken.com/v1/chat/completions（例如 gemini-3-flash-preview）
• •不要使用 /gemini/...:generateContent 调用文本模：现网返回 403「该路径仅支持已建模的 Gemini 图结算模型」——图模出图另见场景表
• •不要调用 /gemini/v1beta/cachedContents：现网返回 404「不支持的网关路径，已禁止免计费透传」——领风未开放显式 Context Cache
• •Chat 回包可见 usage.prompt_tokens_details.cached_tokens；字段可用，是否缓存命中以实调用回包为准
• •亦可见 usage.completion_tokens_details.reasoning_tokens（思考消耗计量，不等于提示缓存命中）
• •稳定长前缀建议置于 messages 靠前位置；是否隐式命中以回包 cached_tokens 为准，请勿套用 Claude/GPT 显式字段

缓存成功判定

常见问题

• •评测或日志里的 prompt_cache_enabled 若来自客户端 meta，不是 EntHub AI 的「关缓存」开关。
• •官方 OpenAI 文档写 Chat Completions 也可带 5.6 断点；经本平台当前算力链路，GPT-5.6 请用 Responses 观测缓存，Chat 路径实测不记账命中。
• •Claude 即使在 Chat Completions 中携带 cache_control，也无法观测 Anthropic 式写入/命中字段——请改用 Messages。
• •请勿将 5.6 的 prompt_cache_options / breakpoint 套用到 gpt-5.5 及更早模型。
• •不要把「必须设置 prompt_cache_key / retention」写成更早代际的开缓存条件——官方默认即可自动缓存。
• •retention 取值写错（如 in-memory 连字符，或给 gpt-5.5 传 in_memory）会导致 400。
• •前缀任何字节变化（时间戳、随机 ID、JSON 键序）都会导致不命中。
• •其它品牌（通义、Gemini、DeepSeek、Kimi、豆包等）请勿照搬本节 Claude/GPT 字段——请先查阅「文本模能力总表」。

仓库示例脚本（需自备 Key）：scripts/examples/prompt-cache-claude-messages.sh、scripts/examples/prompt-cache-gpt-responses.sh（环境变量 ENTHUB_API_KEY、可选 MODEL）。

推理与工具调用（协议选择）

涉及推理强度或函数/工具调用时，适用协议可能与「纯文本 Chat」不同。GPT-5.6 等模型在 Chat Completions 上携带 tools 时，常返回 400，需改用 Responses。下列按模型目录能力标签列出在售文本模，并给出推荐路径与最小示例。

能力列来自模型目录 category（Thinking / Function Calling）。是否对本企业开通，以控制台模型权限为准。

协议选择

• •OpenAI：推理模优先 Responses；自 GPT-5.4 起，Chat 上 tools 与非 none 的 reasoning_effort 不可同用。GPT-5.6 默认会推理，在 Chat 上携带 tools 时常直接返回 400，请改用 /v1/responses。
• •OpenAI Responses 工具形状与 Chat 不同：回包看 function_call；回传结果用 function_call_output（call_id），不要照搬 role=tool。
• •OpenAI 推理参数在 Responses 为 reasoning.effort / reasoning.mode（5.6 可选 pro）；Chat 侧为 reasoning_effort（若仍走 Chat 且 effort=none 才可能带 tools）。
• •Anthropic Claude：工具与扩展思考均走 Messages（/claude/v1/messages）；思考用 thinking；工具用 tools / tool_choice。

Claude（目录能力）

GPT（目录能力）

OpenAI o 系列（目录能力）

通义 / DeepSeek / Kimi：下列按原厂公开协议整理；是否对本企业开通以控制台为准，实调用字段以回包为准。

通义 Qwen（目录能力）

• •目录标 Thinking / Function Calling 的文本模：工具用 OpenAI 兼容 tools / tool_calls（Chat）为主。
• •若走 Responses，工具回传形状可能不同——建议先完成 Chat 验证再试 Responses。
• •请勿将 GPT-5.6 的 reasoning 对象或 Claude thinking 块原样套用到通义。

DeepSeek（目录能力）

• •原厂 Chat 示例可带 thinking（如 type=enabled）与 reasoning_effort；以目标模型是否接受为准。
• •工具：OpenAI 兼容 tools；多轮回传完整 assistant（含 tool_calls）。
• •推理模输出可能含 reasoning 类字段——多轮/工具环按原厂要求原样回传。

Kimi（目录能力）

• •K3 等思考模常默认开启思考；可用顶层 reasoning_effort（如 low/high/max）调节。
• •工具环必须把完整 assistant 消息（含 reasoning_content 与 tool_calls）追加回 messages，只留 content 会断链。
• •kimi-k2.7-code 等：保留思考可能强制开启——以原厂该 ID 说明为准。

curl -X POST "https://api.lingfengtoken.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6-cn",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "现在几点？若需要请调用工具。" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_time",
          "description": "获取当前时间",
          "parameters": { "type": "object", "properties": {} }
        }
      }
    ]
  }'

Gemini：推理计量与工具

• •Chat 成功回包可含 completion_tokens_details.reasoning_tokens——表示推理 token 计量，不是「开了 thinkingConfig」的原厂原生块。
• •原生 generateContent + thinkingConfig / functionDeclarations：文本模在领风被 403 拦住；图结算模才走 /gemini 原生路径。
• •Chat + tools：现网尚未形成可复用示例——对接工具前请先小流量验证。
• •区域不可用：个别 ID（如 gemini-3.1-flash-lite）可能因算力区域限制返回 403，与协议无关。

示例：GPT 推理（Responses）

curl -X POST "https://api.lingfengtoken.com/v1/responses" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "用三句话解释什么是提示缓存",
    "max_output_tokens": 256,
    "reasoning": { "effort": "low" }
  }'

示例：GPT 工具调用（Responses）

curl -X POST "https://api.lingfengtoken.com/v1/responses" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "上海现在天气怎么样？",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "按城市查询天气",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"],
          "additionalProperties": false
        },
        "strict": true
      }
    ],
    "reasoning": { "effort": "low" }
  }'

若 Responses 回包出现 type=function_call：本地执行后，用 type=function_call_output 且同一 call_id 回传；推理模建议带回 reasoning 项或使用 previous_response_id。不要把 Chat 的 role=tool 原样丢进 Responses。

示例：Claude 工具调用（Messages）

curl -X POST "https://lingfengtoken.com/api/claude/v1/messages" \
  -H "Authorization: Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 512,
    "tools": [
      {
        "name": "get_weather",
        "description": "按城市查询天气",
        "input_schema": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    ],
    "messages": [
      { "role": "user", "content": "上海天气如何？" }
    ]
  }'

常用客户端接入

计费说明

错误排查

错误响应示例：

{
  "error": {
    "code": "APP_MODEL_NOT_ALLOWED",
    "message": "应用未授权调用模型 gpt-4o",
    "type": "billing_error"
  }
}

EntHub AI 暂未开放的能力

附录：地址一览

鉴权（唯一）：

默认使用 Bearer sk-lf-。Claude Code 通过 x-api-key 发送 sk-lf- 时，/claude 路径已支持。Gemini 原生请用 Bearer，勿用 x-goog-api-key。

多语言 Chat 示例

import requests

resp = requests.post(
    "https://api.lingfengtoken.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": "你好"}],
    },
    timeout=60,
)
print(resp.status_code, resp.json())

const res = await fetch("https://api.lingfengtoken.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk-lf-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "你好" }],
  }),
});
console.log(await res.json());