通用对话接口

介绍

该接口为通用的智能体对话API，根据用户输入生成智能体的响应结果，通过一个接口融合LinkAI的各项能力：

支持通过绑定应用、工作流 或 超级AI助理，使用其背后的 知识库、插件、技能等能力
支持一键切换所有支持的 大模型
支持 流式/非流式 输出，兼容 OpenAI 的接口结构
支持 多模态输入/输出，可输入文字、图片；输出文字、图片、视频、文件

接口定义

接口地址

POST https://api.link-ai.tech/v1/chat/completions

请求头

参数	取值	说明
Authorization	Bearer YOUR_API_KEY	参考接口鉴权说明创建 API Key 并填入
Content-Type	application/json	表明使用JSON格式请求

请求体

参数	类型	是否必传	说明
messages	`list<object>`	是	消息上下文列表，其中每个元素的结构为 `{"role": "user", "content": "你好"}`， role 字段支持填写 system, user, assistant 中的一个，content字段不能为空
app_code	`string`	否	应用、工作流或超级AI助理的 code。若不填则表示不绑定具体应用，将请求直接传递给模型
model	`string`	否	模型编码，不传则使用应用的默认模型。所有可选模型见模型列表。当 `app_code` 指定为超级AI助理时，该字段无效，实际模型由助理自身配置决定
session_id	`string`	否	会话 ID。当 `app_code` 指定为超级AI助理时有效，传入则复用该会话的上下文与记忆，不传将自动生成一次性会话
temperature	`float`	否	温度，默认为应用中配置的温度。取值范围为 [0, 1]，温度越高回复越具有创意和不确定性，温度越低则回复更严谨
top_p	`int`	否	控制模型采样范围，默认值为 1
frequency_penalty	`float`	否	频率惩罚项，该参数越大则更倾向于产生不同的内容，范围为 [-2, 2]，默认值为 0
presence_penalty	`float`	否	存在惩罚项，该参数越大则更倾向于产生不同的内容，范围为 [-2, 2]，默认值为 0
stream	`bool`	否	是否流式输出，默认值为 false
stream_options	`object`	否	当 stream 为 true 时有效，设置为 `{"include_usage": true}` 时流式输出最后一个chunk将包含 token 用量信息，默认为false
stop	`list<string>`	否	停止词列表，模型生成内容遇到列表中的字符串时将停止输出，最多可填 4 个
tool_choice	`string`	否	工具选择模式，auto:自动选择, none:不会调用, required:必须调用一个或多个tool
tools	`list<object>`	否	工具列表，当使用 Function Call 功能时需要传入，详见 Function Call
response_format	`object`	否	输出格式设置，设置为 `{"type": "json_object"}` 时将约束模型按照JSON格式输出。注意同时需要在提示词中告知模型以JSON格式输出
thinking	`object`	否	LinkAI 扩展字段，用于控制模型的思考/推理开关。`{"type": "enabled"}` 强制开启思考，`{"type": "disabled"}` 强制关闭。优先级高于应用与模型默认配置，详见思考与推理控制
reasoning_effort	`string`	否	推理强度，控制推理模型在思考阶段消耗的 token 数。常用取值 `minimal` / `low` / `medium` / `high`。仅对支持该参数的推理模型生效（如 OpenAI o / gpt-5 系列、DeepSeek V4 等），具体取值范围与默认值由模型决定，其他模型会忽略此字段

注意：

当通过 app_code 参数指定了应用时，将会默认使用 应用设定 作为系统提示词，使用应用中配置的 默认模型 作为model，使用 应用的温度 作为 temperature 的值
当通过 app_code 参数指定了工作流时，接口调用后将会从开始节点执行工作流，并将结束节点的输出通过接口返回
当通过 app_code 参数指定了超级AI助理时，接口将由助理自动选择模型、调用插件与技能完成任务，详见调用超级AI助理

请求示例:

{
    "app_code": "G7z6vKwp",
    "messages": [
        { "role": "user", "content": "你好" }
    ]
}

注意：app_code 需换成你自己创建应用的code、应用广场中公开应用的code，或不指定应用（不指定应用时直接调用底层模型能力）。

响应结果

非流式响应

接口调用默认为非流式响应，会在所有内容生成完毕后一次性返回：

{
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "你好，请问有什么可以帮助您的吗？"
            }
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 17,
        "total_tokens": 26
    }
}

注意：

choices.message.content 中为AI的响应内容，usage 部分 prompt_tokens、completion_tokens、total_tokens 分别表示请求的token数、响应的token数、全部消耗的token数，这三个费用相关字段直接使用模型返回的结果，平台不做处理。
一次对话的token计算包含请求和响应中的总token数，其中请求又包含 应用设定、历史对话、知识库内容、用户问题，这些几个部分的token长度限制都可以在应用管理中找到。

流式响应

流式调用需要将传入参数 stream 设置为 true，将会在模型不断生成内容的过程中实时返回，适用于网页、APP、小程序等调用端进行流式输出：

data: {"choices": [{"index": 0, "delta": {"content": "你好！"}, "finish_reason": null}], "session_id": null}

data: {"choices": [{"index": 0, "delta": {"content": "我能"}, "finish_reason": null}], "session_id": null}

data: {"choices": [{"index": 0, "delta": {"content": "为你"}, "finish_reason": null}], "session_id": null}

data: {"choices": [{"index": 0, "delta": {"content": "做些什么？"}, "finish_reason": null}], "session_id": null}

data: {"choices": [{"index": 0, "delta": {}, "finish_reason": "stop", "usage": {"prompt_tokens": 9, "completion_tokens": 6, "total_tokens": 15}}], "session_id": null}

data: [DONE]

注意：

当输出为 "[DONE]" 时表示输出结束
输入参数中包含 "stream_options": {"include_usage": true} 时，流式输出的最后一个chunk将包含token用量信息

错误说明

当接口异常时会返回以下结构：

{
    "error": {
        "message": "Invalid request: user message content is empty",
        "type": "invalid_request_error"
    }
}

根据 HTTP状态码 (status code) 和错误信息判断错误类型：

HTTP状态码	描述
400	请求格式错误
401	接口鉴权失败，请检查 API Key 是否填写正确
402	应用不存在，请检查 app_code 参数是否正确
403	无访问权限，对于未公开应用，只有创建者账号才能调用
406	账号积分额度不足
409	内容审核不通过，问题、回答、检索的知识库中可能存在敏感词
429	触发应用调用频率限制，请稍后重试
503	接口调用异常，联系客服处理

额外字段

在返回结果中，LinkAI 还会提供一些扩展字段方便进行智能体开发：

knowledge_base: 知识库检索信息，其中 search_hit 字段表示是否检索命中，first_similarity 为首条命中的知识库记录的相似度
suggested_questions: 当应用开启了 问题推荐 时返回，内容为模型推荐的问题列表，用于引导用户进一步提问
agent: 当本次对话触发了 应用插件 / 技能 时返回，包含插件执行链信息，结构为 {"status": "...", "chain": [{"plugin_name": "...", "thought": "...", "plugin_input": "...", ...}], "need_show_plugin": true}，可用于在前端展示插件调用过程
trace_id: 本次请求的链路 ID，用于排查问题

模型列表

接口支持的所有模型列表如下，完整模型列表可在平台模型管理页面查看，或调用模型列表接口查询。

若不传 model 参数，则会使用智能体中配置的默认模型，各模型价格以模型管理页面为准。

示例代码

文本对话

1.CURL请求

非流式输出
流式输出
Function Call示例
JSON Format示例

curl --request POST \
  --url https://api.link-ai.tech/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_code": "",
  "messages": [
    {
      "role": "user",
      "content": "你是谁"
    }
  ]
}'

curl --request POST \
  --url https://api.link-ai.tech/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_code": "",
  "messages": [
    {
      "role": "user",
      "content": "你是谁"
    }
  ],
  "stream": true,
  "stream_options": {"include_usage": true}
}'

curl --request POST \
  --url https://api.link-ai.tech/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_code": "",
  "messages": [
    {
      "role": "user",
      "content": "北京今天天气怎么样？"
    }
  ],
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}'

curl --request POST \
  --url https://api.link-ai.tech/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_code": "",
  "messages": [
    {
      "role": "user",
      "content": "使用JSON格式结构化输出以下数据：\n姓名：张三，年龄：28，性别：男"
    }
  ],
  "response_format": {"type": "json_object"}
}'

注意：在 YOUR_API_KEY 处填入你创建的 API Key，在 app_code 中填入你创建的应用code。

2.Python代码请求

非流式输出
流式输出

import requests

url = "https://api.link-ai.tech/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
body = {
    "app_code": "",
    "messages": [
        {
            "role": "user",
            "content": "你好"
        }
    ]
}
res = requests.post(url, json=body, headers=headers)
if res.status_code == 200:
    reply_text = res.json().get("choices")[0]['message']['content']
    print(reply_text)
else:
    error = res.json().get("error")
    print(f"请求异常, 错误码={res.status_code}, 错误类型={error.get('type')}, 错误信息={error.get('message')}")

import json
import requests

url = "https://api.link-ai.tech/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
body = {
    "app_code": "",
    "messages": [
        {
            "role": "user",
            "content": "写一个登录模块的设计文档"
        }
    ],
    "stream": True,
}
res = requests.post(url, json=body, headers=headers, stream=True)
for i in res.iter_lines():
    st = str(i, encoding="utf-8")
    st = st.replace("data: ", "", 1)
    if st:
        if st == "[DONE]":                  # 输出结束
            break
        chunk = json.loads(st)
        if not chunk.get("choices"):
            continue
        chunk_message = chunk["choices"][0]["delta"].get("content")
        if chunk_message:
            print(chunk_message, end="")    # 输出每一段数据

注意：

在 YOUR_API_KEY 处填入你创建的 API Key，在 app_code 中填入你创建的应用code。
如果你使用的是 openai 的SDK，可以通过修改 api_base 配置快速完成键入，详见 OpenAI兼容

3.更多语言和在线调试

其他编程语言的接入代码可以在 API调试页面进行代码生成，同时支持在线进行接口调试。

Function Call

支持以与 OpenAI 完全兼容的方式使用 Function Call（工具调用），通过 tools 与 tool_choice 字段声明可调用的函数，由模型自动判断是否调用、生成调用参数，业务侧执行工具后将结果回传给模型生成最终回复。

1. 发起调用

在请求中声明 tools（可选 tool_choice 控制调用模式）：

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "北京今天天气怎么样？" }
  ],
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名称" }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

2. 模型决定调用工具

当模型判断需要调用工具时，响应中 finish_reason 为 tool_calls，message.tool_calls 包含模型生成的工具调用参数：

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"北京\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

3. 回传工具结果

业务侧执行工具后，将结果以 role: "tool" 的消息追加到 messages 中再次发起请求，模型基于工具结果生成最终回复：

{
  "model": "deepseek-v4-flash",
  "messages": [
    { "role": "user", "content": "北京今天天气怎么样？" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": { "name": "get_weather", "arguments": "{\"city\":\"北京\"}" }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"city\":\"北京\",\"weather\":\"晴\",\"temp\":\"20~28°C\"}"
    }
  ],
  "tools": [ /* 同上 */ ]
}

最终响应：

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "北京今天晴，气温 20~28°C。"
      },
      "finish_reason": "stop"
    }
  ]
}

注意：

不同模型对 Function Call 的支持程度不同，建议优先使用 DeepSeek、OpenAI、Claude、Qwen、Gemini、Kimi 等主流模型
若想直接使用 LinkAI 平台内置的插件能力（无需在客户端实现工具逻辑），推荐通过 app_code 绑定应用并在应用中配置插件，或绑定超级AI助理

思考与推理控制

对于 思考模型（如 DeepSeek-R1、DeepSeek-V4、Qwen3、Doubao Seed 1.6、Claude 4 等），LinkAI 提供了思考开关与推理强度两类控制参数，并在响应中通过 reasoning_content 字段返回思考过程。

思考开关 thinking

thinking 为 LinkAI 扩展字段，用于覆盖应用 / 模型的默认思考配置：

取值	说明
`{"type": "enabled"}`	强制开启思考
`{"type": "disabled"}`	强制关闭思考

优先级为：API 请求 thinking 参数 > 应用中针对模型的思考配置 > 模型自身的默认思考开关。

不同模型的默认行为不同，例如 DeepSeek V4 默认开启思考（enabled），如不需要思考过程需显式传入 {"type": "disabled"} 关闭。

请求示例：

{
  "model": "qwen3.6-plus",
  "messages": [
    { "role": "user", "content": "9.11 和 9.8 哪个大？" }
  ],
  "thinking": { "type": "enabled" }
}

推理强度 reasoning_effort

对于支持推理强度调节的模型（如 OpenAI o / gpt-5 系列、DeepSeek V4 等），可通过 reasoning_effort 控制模型在思考阶段的 token 消耗。该字段会被 LinkAI 直接透传给底层模型，取值范围与默认值由具体模型决定，常用取值如下：

取值	说明
`none`	不进行推理（部分新模型支持，如 gpt-5.1）
`minimal`	极低推理强度
`low`	低推理强度，速度快、成本低
`medium`	中等推理强度
`high`	高推理强度，结果更准确但耗时与成本更高
`xhigh`	极高推理强度（部分模型支持，如 gpt-5.1-codex-max 之后）

注意：

不支持该参数的模型（如 Claude、Qwen、Gemini 等）会忽略此字段
不同模型的默认值与有效取值不同，常见示例：
- OpenAI gpt-5.1：默认 none（不推理）
- OpenAI 老版本推理模型（如 o3）：默认 medium，不支持 none
- OpenAI gpt-5-pro：仅支持 high
- DeepSeek V4：思考模式下仅有效取值为 high / max
具体取值范围与默认值以模型官方文档为准

思考内容 reasoning_content

当模型开启思考时，响应中 message.reasoning_content（流式为 delta.reasoning_content）为模型的思考过程，content 为最终回答：

非流式：

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": "用户在问 9.11 和 9.8 哪个大。9.11 = 9 + 0.11，9.8 = 9 + 0.80 ...",
        "content": "9.8 更大。"
      },
      "finish_reason": "stop"
    }
  ]
}

流式：思考阶段每个 chunk 的 delta.reasoning_content 持续输出，思考结束后再开始输出 delta.content。

data: {"choices":[{"delta":{"reasoning_content":"先比较"}}]}

data: {"choices":[{"delta":{"reasoning_content":"小数部分..."}}]}

data: {"choices":[{"delta":{"content":"9.8"}}]}

data: {"choices":[{"delta":{"content":" 更大。"},"finish_reason":"stop"}]}

data: [DONE]

图像识别

支持用户输入图片并根据图片进行问答，使用前提：

对于 应用接入：应用中需启用 "图像识别" 插件
对于 工作流接入：工作流中需使用 "图像识别" 插件

curl https://api.link-ai.tech/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "app_code": "default",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "这张图是什么？"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://cdn.link-ai.tech/doc/vision-model-config.jpg"
            }
          }
        ]
      }
    ]
  }'

注意：

在 YOUR_API_KEY 处填入你创建的 API Key，将 app_code 中的值替换为你创建的应用或工作流的code。
图片url需填写公开网络可访问的图片地址。
图片修改的调用方式与图像识别类似，需要开启 GPT-Image-1 或 AI改图 插件，传入图片url后会输出生成的图片url

超级AI助理

通过对话接口可以直接调用超级AI助理，将助理的智能能力（自动模型选择、技能调用、长期记忆等）接入到 APP、小程序、Web 等自有业务系统。

调用方式：在请求中将 app_code 设置为超级AI助理的应用 code 即可。

与普通应用的差异：

上下文记忆自动维护：messages 数组只需传入最后一条用户消息，历史对话与长期记忆由超级AI助自动维护，无需调用方拼接历史 messages。传入已有 session_id 可复用该会话的上下文，不传则自动生成一次性会话并返回 session_id
model 字段无效：实际模型由超级AI助理自身配置决定，请求中传入的 model 会被忽略，响应中回显的 model 始终为助理配置的主模型
超时：单次调用最长 600s，长任务建议使用流式调用
计费：本接口本身不重复扣费，实际消耗由助理内部各步骤（模型调用、插件调用）按真实模型扣费

请求示例

{
  "app_code": "xxxxxxxx",
  "session_id": "my_session_001",
  "messages": [
    { "role": "user", "content": "帮我查一下最近的天气" }
  ]
}

开启流式输出：在请求中加入 "stream": true。

非流式响应

超级AI助理在执行过程中调用了工具时，会附带 tool_calls（模型发起的工具调用）和 tool_results（工具执行结果）字段：

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1778060000,
  "model": "deepseek-v4-flash",
  "session_id": "my_session_001",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "今天上海多云转晴，气温 18~25°C ...",
        "tool_calls": [
          {
            "id": "call_xxx",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"上海\"}"
            }
          }
        ],
        "tool_results": [
          {
            "tool_call_id": "call_xxx",
            "content": "{\"city\":\"上海\",\"weather\":\"多云转晴\",\"temp\":\"18~25°C\"}"
          }
        ]
      },
      "finish_reason": "stop"
    }
  ]
}

流式响应

返回 text/event-stream，正文 chunk 与 OpenAI chat.completion.chunk 完全兼容（通过 delta.content 增量推送）；工具调用过程通过 LinkAI 扩展字段 extension 透传，便于客户端按需展示「工具开始 / 工具结束」的过程，最终以 data: [DONE] 结束：

extension.type	说明
`tool_start`	工具即将执行，`extension.data` 中包含 `tool` 名称与 `arguments`
`tool_calls`	工具执行完毕，`extension.data` 中包含 `tool_calls` 列表（含 `name`、`arguments`、`result`、`status`、`elapsed`）

data: {"model":"deepseek-v4-flash","session_id":"my_session_001","choices":[{"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"model":"deepseek-v4-flash","session_id":"my_session_001","choices":[{"delta":{},"finish_reason":null},],"extension":{"type":"tool_start","data":{"tool":"get_weather","arguments":{"city":"上海"}}}}

data: {"model":"deepseek-v4-flash","session_id":"my_session_001","choices":[{"delta":{},"finish_reason":null}],"extension":{"type":"tool_calls","data":{"tool_calls":[{"name":"get_weather","arguments":{"city":"上海"},"result":"{\"weather\":\"多云转晴\",\"temp\":\"18~25°C\"}","status":"success","elapsed":"0.3s"}]}}}

data: {"model":"deepseek-v4-flash","session_id":"my_session_001","choices":[{"delta":{"content":"今天"},"finish_reason":null}]}

data: {"model":"deepseek-v4-flash","session_id":"my_session_001","choices":[{"delta":{"content":"上海"},"finish_reason":null}]}

...

data: {"model":"deepseek-v4-flash","session_id":"my_session_001","choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

注意： 客户端如果只关心最终回复，可以忽略所有带 extension 字段的 chunk，按 OpenAI 标准方式拼接 delta.content 即可。

CURL 调用示例

curl --request POST \
  --url https://api.link-ai.tech/v1/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_code": "YOUR_AGENT_APP_CODE",
    "session_id": "my_session_001",
    "messages": [
      { "role": "user", "content": "帮我查一下最近的天气" }
    ],
    "stream": true
  }'

OpenAI兼容

该接口完全兼容 OpenAI的输入和输出格式，所以可以直接使用 OpenAI SDK 完成接入，只需设置 api_base 和 api_key 即可：

1.x 版本
0.x 版本

client = OpenAI(
    base_url = "https://api.link-ai.tech/v1",
    api_key = "YOUR API KEY"
)

openai.api_base = "https://api.link-ai.tech/v1"
openai.api_key = "YOUR API KEY"

如果需要在使用 OpenAI SDK 的同时指定应用，可以将 app_code 参数使用 "-" 分隔符拼接在 api_key 参数的后面，例如 Link_tOCJYmHxxm55eA1xs-Kv2fXJcH2。

通用对话接口

介绍​

接口定义​

接口地址​

请求头​

请求体​

响应结果​

非流式响应​

流式响应​

错误说明​

额外字段​

模型列表​

示例代码​

文本对话​

1.CURL请求​

2.Python代码请求​

3.更多语言和在线调试​

Function Call​

1. 发起调用​

2. 模型决定调用工具​

3. 回传工具结果​

思考与推理控制​

思考开关 thinking​

推理强度 reasoning_effort​

思考内容 reasoning_content​

图像识别​

超级AI助理​

请求示例​

非流式响应​

流式响应​

CURL 调用示例​

OpenAI兼容​

介绍

接口定义

接口地址

请求头

请求体

响应结果

非流式响应

流式响应

错误说明

额外字段

模型列表

示例代码

文本对话

1.CURL请求

2.Python代码请求

3.更多语言和在线调试

Function Call

1. 发起调用

2. 模型决定调用工具

3. 回传工具结果

思考与推理控制

思考开关 thinking

推理强度 reasoning_effort

思考内容 reasoning_content

图像识别

超级AI助理

请求示例

非流式响应

流式响应

CURL 调用示例

OpenAI兼容