Digital Employee OpenAI-Compatible API

Published Digital Employees can be integrated into business systems, server-side applications, and OpenAI clients that support a custom Base URL through the OpenAI-compatible API.

The Digital Employee API provides two endpoints:

• Chat Completions API: stateless calls that return only the final user-visible text.
• Responses API: persistent sessions that return standard reasoning, tool calls, complete tool outputs, and final text.

Before You Call the API

Publish to the API Channel

On the Digital Employee detail page, click Publish, enable API Call, and complete publishing. A Digital Employee cannot be called through the API when its API channel is disabled, it is disabled, or it is unpublished.

The Digital Employee owner must also have Use permission on the Digital Employee. If the Digital Employee uses workstations, MCP servers, skills, or other governed resources, configure those resources and permissions first.

Obtain the Call Parameters

Each call requires the following values:

Parameter	Description
Base URL	https://gendial.cn/api/v1. For a private deployment, replace the domain with the actual site while keeping /api/v1.
model	The stable Digital Employee ID (employeeId). It is available in the Digital Employee detail URL /digiemployee/<employeeId>.
API Key	The API key generated for the Digital Employee. Obtain it from the Digital Employee owner or platform administrator.

Send the API Key using HTTP Bearer Authentication:

Authorization: Bearer YOUR_DE_API_KEY

Security Notice

Call the API only from a trusted server. Never place the API Key in browser or mobile application code, public repositories, logs, or screenshots. Resetting the Digital Employee API Key invalidates the previous key immediately.

Choose an API

Scenario	Recommended endpoint	Session model	Returned content
The client manages complete message history and needs only the final answer	/chat/completions	Stateless	Final visible text
Server-side multi-turn history and persistent sessions are required	/responses	Client UUID memoryId	Reasoning, tool trace, tool output, and final text
The client needs to inspect tools executed by the Digital Employee	/responses	Client UUID memoryId	Standard Responses output items/events
A third-party client supports only Chat Completions	/chat/completions	Send complete history every time	Final visible text

Chat Completions API

Request Rules

POST /api/v1/chat/completions is stateless:

• model must be the Digital Employee employeeId.
• messages must be a non-empty array ending with a user message.
• Text-only system, developer, user, and assistant messages are supported.
• The client must send all conversation history needed for every request.
• memoryId is not supported. Use the Responses API for persistent sessions.
• Chat tool messages, client tools, and tool_choice are not supported.
• Only text content is currently supported; Chat image_url content parts are not supported.

Tools configured for the Digital Employee still execute on the server, but a Chat Completions response returns only final visible text. It does not expose reasoning, tool calls, or tool outputs.

Non-Streaming cURL Example

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": "Answer concisely."
      },
      {
        "role": "user",
        "content": "Summarize this week’s project progress."
      }
    ]
  }'

The final text is available at:

choices[0].message.content

Streaming cURL Example

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": "Describe the work you can perform."
      }
    ]
  }'

The stream uses standard chat.completion.chunk objects and ends with data: [DONE]. It contains only visible final-answer text deltas.

Python OpenAI SDK Example

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": "Create a meeting agenda."},
    ],
)

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

Responses API

Session Management

POST /api/v1/responses uses a client-provided UUID memoryId to save and restore the Digital Employee session:

1. Generate a new UUID on the client before starting a conversation.
2. Include that memoryId in the first request.
3. Reuse the same memoryId for subsequent turns and send only the current turn each time.
4. Generate a new UUID to start another conversation.
5. Do not use the same memoryId for different Digital Employees or call the same memoryId concurrently.

The response does not return memoryId; the client must retain it. The Responses API does not support previous_response_id.

Python UUID example:

from uuid import uuid4

memory_id = str(uuid4())

Text Request cURL Example

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": "List the information sources in your answer.",
    "input": "Analyze this task and execute any necessary tools."
  }'

Continue the conversation with the same memoryId:

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": "Continue from the previous result and create the final report."
  }'

Python OpenAI SDK Example

memoryId is a Gendial request field. With the Python OpenAI SDK, add it through extra_body:

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="Review the project status and recommend next steps.",
    extra_body={"memoryId": memory_id},
)

print(response.output_text)

response = client.responses.create(
    model="YOUR_DE_EMPLOYEE_ID",
    input="Continue with the first recommendation.",
    extra_body={"memoryId": memory_id},
)

print(response.output_text)

Image Input

The Responses API supports standard input_text and input_image content parts. image_url may be an HTTPS URL accessible to the Digital Employee service or an image Data URL.

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": "Analyze this image."
          },
          {
            "type": "input_image",
            "image_url": "https://example.com/image.png"
          }
        ]
      }
    ]
  }'

Responses input currently supports text and images only. Client file items and client tool outputs are not supported.

Response Content

A non-streaming result is a standard response object. Common output items appear in the Digital Employee’s actual execution order:

type	Description
reasoning	Digital Employee reasoning text
function_call	A tool call and JSON arguments already initiated on the server
function_call_output	The complete result of the corresponding tool execution
message	The final user-visible answer

The final visible text is also available directly as response.output_text. The response does not add memoryId, reasoning_content, or any gendial_* custom field.

Streaming Response

Set "stream": true to receive standard Responses SSE events:

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": "Retrieve the relevant information and summarize it."
  }'

Events include:

• 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, or error

Every event contains an increasing sequence_number. A Responses stream does not send the Chat Completions data: [DONE] marker.

Tool Execution Semantics

Digital Employee tools are selected and executed automatically by the server according to the Digital Employee configuration:

• The client must not send tools, Chat tool messages, or tool outputs.
• A function_call is a server-initiated tool trace whose execution is managed by the server; it is not a request for the client to execute a tool.
• The corresponding function_call_output is returned by the server and may contain multiple text or image content parts.
• If only the final answer is needed, use Chat Completions or read Responses response.output_text directly.

Per-request sampling, model selection, and tool policy follow the Digital Employee’s platform configuration. Do not rely on request fields to override the Digital Employee runtime configuration.

Common Errors

Errors use the standard OpenAI envelope:

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

HTTP status	code	Description
400	memory_id_required	A Responses request is missing memoryId
400	invalid_memory_id	memoryId is not a UUID
400	use_responses_api_for_persistent_session	A Chat Completions request incorrectly includes memoryId
400	previous_response_id_not_supported	Use memoryId; previous_response_id is not supported
400	client_tools_not_supported	The client sent tool definitions, tool messages, or unsupported tool selection
401	invalid_api_key	The API Key is missing or incorrect
403	model_disabled	The Digital Employee is disabled
403	channel_not_supported	The Digital Employee is not published to the API channel
403	permission_denied	Use permission is not available for the Digital Employee
404	model_not_found	The Responses API cannot find the specified Digital Employee
409	ambiguous_target	The same model matches both a Digital Employee and Workflow
409	session_busy	Another request is already running for the same memoryId
429	rate_limit_exceeded	Requests are too frequent; both DE endpoints share a 20 requests/second limit

Security and Operational Guidance

• Store each integration’s API Key securely and restrict the people and services that can read it.
• Do not send userId, ownerId, or tenantId in the request body; the server uses only authoritative identity data loaded from the database.
• Assign a separate memoryId to each user or business conversation so that different users never share conversation history.
• If a client disconnects from a streaming response, the platform cancels the current Digital Employee execution. Send a new request when work must continue.
• Before calling a Digital Employee that uses workstation or local tools, verify that the target workstation and required connections are available.