数字员工 OpenAI 兼容 API

已发布的数字员工可以通过 OpenAI 兼容 API 接入业务系统、服务端程序和支持自定义 Base URL 的 OpenAI 客户端。

数字员工 API 提供两个端点：

Chat Completions API：无状态调用，只返回数字员工最终对用户可见的文本。
Responses API：持久会话调用，返回标准 reasoning、工具调用、完整工具结果和最终文本。

调用前准备

发布到 API 渠道

在数字员工详情页点击发布，打开 API 调用 开关并完成发布。未启用 API 渠道、已停用或已取消发布的数字员工不能通过 API 调用。

数字员工所有者还必须拥有该数字员工的 使用（Use） 权限。如果数字员工会使用工作站、MCP、技能或其他受控资源，也应提前完成相应配置和权限授权。

获取调用参数

调用需要以下参数：

参数	说明
Base URL	`https://gendial.cn/api/v1`。私有化部署请替换为实际站点域名并保留 `/api/v1`。
`model`	数字员工稳定 ID（`employeeId`）。可以从数字员工详情页 URL `/digiemployee/<employeeId>` 中获取。
API Key	数字员工创建时生成的 API 密钥。请向数字员工所有者或平台管理员获取。

API Key 通过 HTTP Bearer Authentication 发送：

http

Authorization: Bearer YOUR_DE_API_KEY

安全提示

只应从可信的服务端调用 API。不要把 API Key 写入浏览器、移动端应用、公开代码仓库、日志或截图。重置数字员工 API Key 后，旧 Key 会立即失效。

选择 API

场景	推荐端点	会话方式	返回内容
客户端自行维护完整消息历史，只需要最终答案	`/chat/completions`	无状态	最终可见文本
需要服务端保存多轮历史和长期会话	`/responses`	客户端 UUID `memoryId`	reasoning、工具轨迹、工具结果、最终文本
需要查看数字员工在服务端执行工具的过程	`/responses`	客户端 UUID `memoryId`	标准 Responses output items/events
使用只支持 Chat Completions 的第三方客户端	`/chat/completions`	每次发送完整历史	最终可见文本

Chat Completions API

请求规则

POST /api/v1/chat/completions 是无状态接口：

model 必须是数字员工的 employeeId。
messages 必须是非空数组，并以 user 消息结束。
支持 system、developer、user、assistant 的纯文本消息。
客户端必须在每次请求中发送所需的完整对话历史。
不支持 memoryId。需要持久会话时请使用 Responses API。
不支持 Chat tool 消息、客户端 tools 或 tool_choice。
当前只支持文本内容，不支持 Chat image_url 内容块。

数字员工配置的工具仍会在服务端正常执行，但 Chat Completions 响应只返回最终可见文本，不返回 reasoning、工具调用或工具结果。

非流式 cURL 示例

bash

curl https://gendial.cn/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DE_API_KEY" \
  -d '{
    "model": "YOUR_DE_EMPLOYEE_ID",
    "messages": [
      {
        "role": "system",
        "content": "请用简洁的中文回答。"
      },
      {
        "role": "user",
        "content": "总结本周项目进展。"
      }
    ]
  }'

最终文本位于：

text

choices[0].message.content

流式 cURL 示例

bash

curl -N https://gendial.cn/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DE_API_KEY" \
  -d '{
    "model": "YOUR_DE_EMPLOYEE_ID",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": "介绍一下你能完成的工作。"
      }
    ]
  }'

流式响应使用标准 chat.completion.chunk，以 data: [DONE] 结束。流中只包含最终回答的文本增量。

Python OpenAI SDK 示例

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DE_API_KEY",
    base_url="https://gendial.cn/api/v1",
)

completion = client.chat.completions.create(
    model="YOUR_DE_EMPLOYEE_ID",
    messages=[
        {"role": "user", "content": "请生成一份会议议程。"},
    ],
)

print(completion.choices[0].message.content)

Responses API

会话管理

POST /api/v1/responses 使用客户端提供的 UUID memoryId 保存和恢复数字员工会话：

开始新对话前，由客户端生成一个新的 UUID。
第一次请求就必须发送该 memoryId。
同一对话的后续请求重复使用同一个 memoryId，每次只发送当前一轮输入。
开始另一段新对话时生成新的 UUID。
不要把同一个 memoryId 用于不同数字员工，也不要并发调用同一个 memoryId。

memoryId 不会出现在响应中，客户端必须自行保存。Responses API 不支持 previous_response_id。

Python 生成 UUID 的示例：

python

from uuid import uuid4

memory_id = str(uuid4())

文本请求 cURL 示例

bash

curl https://gendial.cn/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DE_API_KEY" \
  -d '{
    "model": "YOUR_DE_EMPLOYEE_ID",
    "memoryId": "69a6e23f-421f-4ec8-97c4-b7326676e59b",
    "instructions": "回答时列出信息来源。",
    "input": "分析这份任务并执行必要的工具。"
  }'

后续对话继续使用同一个 memoryId：

bash

curl https://gendial.cn/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DE_API_KEY" \
  -d '{
    "model": "YOUR_DE_EMPLOYEE_ID",
    "memoryId": "69a6e23f-421f-4ec8-97c4-b7326676e59b",
    "input": "根据刚才的结果继续生成最终报告。"
  }'

Python OpenAI SDK 示例

memoryId 是 Gendial 的请求字段。使用 Python OpenAI SDK 时，通过 extra_body 添加：

python

from uuid import uuid4
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_DE_API_KEY",
    base_url="https://gendial.cn/api/v1",
)

memory_id = str(uuid4())

response = client.responses.create(
    model="YOUR_DE_EMPLOYEE_ID",
    input="检查项目状态并给出下一步建议。",
    extra_body={"memoryId": memory_id},
)

print(response.output_text)

response = client.responses.create(
    model="YOUR_DE_EMPLOYEE_ID",
    input="继续完成第一项建议。",
    extra_body={"memoryId": memory_id},
)

print(response.output_text)

图片输入

Responses API 支持标准 input_text 和 input_image 内容块。image_url 可以是数字员工服务能够访问的 HTTPS URL，也可以是图片 Data URL。

bash

curl https://gendial.cn/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DE_API_KEY" \
  -d '{
    "model": "YOUR_DE_EMPLOYEE_ID",
    "memoryId": "69a6e23f-421f-4ec8-97c4-b7326676e59b",
    "input": [
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "分析这张图片。"
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.png"
          }
        ]
      }
    ]
  }'

当前 Responses 输入只支持文本和图片，不支持客户端文件 item 或客户端工具结果。

响应内容

非流式响应是标准 response 对象。常见 output item 按数字员工实际执行顺序出现：

`type`	说明
`reasoning`	数字员工的 reasoning 文本
`function_call`	数字员工已经在服务端发起的工具调用及 JSON 参数
`function_call_output`	对应工具已经执行完成的完整结果
`message`	最终对用户可见的回答

最终可见文本也可以直接从 response.output_text 读取。响应不会增加 memoryId、reasoning_content 或 gendial_* 自定义字段。

流式响应

设置 "stream": true 可以获得标准 Responses SSE 事件：

bash

curl -N https://gendial.cn/api/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_DE_API_KEY" \
  -d '{
    "model": "YOUR_DE_EMPLOYEE_ID",
    "memoryId": "69a6e23f-421f-4ec8-97c4-b7326676e59b",
    "stream": true,
    "input": "检索相关资料并总结。"
  }'

事件包括：

response.created
response.in_progress
response.output_item.added
response.reasoning_text.delta
response.function_call_arguments.delta
response.function_call_arguments.done
response.output_text.delta
response.output_item.done
response.completed、response.failed 或 error

每个事件都有递增的 sequence_number。Responses 流不会发送 Chat Completions 的 data: [DONE] 标记。

工具执行语义

数字员工的工具由服务端根据数字员工配置自动选择和执行：

客户端不要发送 tools、Chat tool 消息或工具结果。
function_call 是由服务端发起并负责执行的工具轨迹，不是在要求客户端执行工具。
对应的 function_call_output 由服务端返回，可能包含多个文本或图片内容块。
如果只需要最终答案，请使用 Chat Completions API，或直接读取 Responses 的 response.output_text。

单次请求中的采样、模型选择和工具策略以数字员工的平台配置为准；不要依赖请求参数覆盖数字员工的运行配置。

常见错误

错误使用 OpenAI 标准 envelope：

json

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

HTTP 状态	`code`	说明
400	`memory_id_required`	Responses 请求缺少 `memoryId`
400	`invalid_memory_id`	`memoryId` 不是 UUID
400	`use_responses_api_for_persistent_session`	Chat Completions 错误携带了 `memoryId`
400	`previous_response_id_not_supported`	应使用 `memoryId`，不能使用 `previous_response_id`
400	`client_tools_not_supported`	客户端发送了工具定义、工具消息或不支持的工具选择
401	`invalid_api_key`	API Key 缺失或错误
403	`model_disabled`	数字员工已停用
403	`channel_not_supported`	数字员工未发布到 API 渠道
403	`permission_denied`	数字员工缺少使用权限
404	`model_not_found`	Responses API 找不到指定数字员工
409	`ambiguous_target`	同一 `model` 同时匹配数字员工和工作流
409	`session_busy`	同一 `memoryId` 已有请求正在执行
429	`rate_limit_exceeded`	请求过于频繁；两个 DE API 端点共享每秒 20 次限制

安全和运行建议

为每个接入系统安全保存 API Key，并限制能够读取密钥的人员和服务。
不要在请求体中传递 userId、ownerId 或 tenantId；服务端只使用数据库中的权威身份信息。
为每个用户或业务会话分配独立的 memoryId，避免不同用户共享对话历史。
客户端断开流式连接时，平台会取消当前数字员工执行；需要继续时请重新发起请求。
调用包含工作站或本地工具的数字员工前，确认目标工作站和所需连接处于可用状态。

数字员工 OpenAI 兼容 API ​

调用前准备 ​

发布到 API 渠道 ​

获取调用参数 ​

选择 API ​

Chat Completions API ​

请求规则 ​

非流式 cURL 示例 ​

流式 cURL 示例 ​

Python OpenAI SDK 示例 ​

Responses API ​

会话管理 ​

文本请求 cURL 示例 ​

Python OpenAI SDK 示例 ​

图片输入 ​

响应内容 ​

流式响应 ​

工具执行语义 ​

常见错误 ​

安全和运行建议 ​

数字员工 OpenAI 兼容 API

调用前准备

发布到 API 渠道

获取调用参数

选择 API

Chat Completions API

请求规则

非流式 cURL 示例

流式 cURL 示例

Python OpenAI SDK 示例

Responses API

会话管理

文本请求 cURL 示例

Python OpenAI SDK 示例

图片输入

响应内容

流式响应

工具执行语义

常见错误

安全和运行建议