跳转到主要内容
POST
/
v1
/
chat
/
completions
创建聊天补全
curl --request POST \
  --url https://api.dedaluslabs.ai/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "content": "Hello, how are you?",
      "role": "user"
    }
  ],
  "input": "Translate this paragraph into French.",
  "temperature": 0,
  "top_p": 0.1,
  "max_tokens": 100,
  "presence_penalty": -0.5,
  "frequency_penalty": -0.5,
  "logit_bias": {
    "50256": -100
  },
  "stop": [
    "\n",
    "END"
  ],
  "thinking": {
    "budget_tokens": 2048,
    "type": "enabled"
  },
  "top_k": 40,
  "system": "You are a helpful assistant.",
  "instructions": "You are a concise assistant.",
  "generation_config": {
    "candidateCount": 2,
    "responseMimeType": "application/json"
  },
  "safety_settings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_NONE"
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    }
  },
  "disable_automatic_function_calling": true,
  "seed": 42,
  "user": "user-123",
  "n": 1,
  "stream": false,
  "stream_options": {
    "include_usage": true
  },
  "response_format": {
    "type": "text"
  },
  "tools": [
    {
      "function": {
        "description": "获取某个位置的当前天气",
        "name": "get_weather",
        "parameters": {
          "properties": {
            "location": {
              "description": "城市名称",
              "type": "string"
            }
          },
          "required": [
            "location"
          ],
          "type": "object"
        }
      },
      "type": "function"
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "functions": [
    {}
  ],
  "function_call": "<string>",
  "logprobs": true,
  "top_logprobs": 5,
  "max_completion_tokens": 1000,
  "reasoning_effort": "medium",
  "audio": {
    "format": "mp3",
    "voice": "alloy"
  },
  "modalities": [
    "text"
  ],
  "prediction": {},
  "metadata": {
    "session": "abc",
    "user_id": "123"
  },
  "store": true,
  "service_tier": "auto",
  "prompt_cache_key": "<string>",
  "safety_identifier": "<string>",
  "verbosity": "low",
  "web_search_options": {},
  "search_parameters": {},
  "deferred": true,
  "mcp_servers": [
    "dedalus-labs/brave-search",
    "dedalus-labs/github-api"
  ],
  "guardrails": [
    {}
  ],
  "handoff_config": {},
  "model_attributes": {
    "anthropic/claude-3-5-sonnet": {
      "cost": 0.7,
      "creativity": 0.8,
      "intelligence": 0.95
    },
    "openai/gpt-4": {
      "cost": 0.8,
      "intelligence": 0.9,
      "speed": 0.6
    },
    "openai/gpt-4o-mini": {
      "cost": 0.2,
      "intelligence": 0.7,
      "speed": 0.9
    }
  },
  "agent_attributes": {
    "accuracy": 0.9,
    "complexity": 0.8,
    "efficiency": 0.7
  },
  "max_turns": 5,
  "auto_execute_tools": true
}
'
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "The next Warriors game is tomorrow at 7:30 PM.",
        "role": "assistant"
      }
    }
  ],
  "created": 1677652288,
  "id": "chatcmpl-123",
  "model": "gpt-4o-mini",
  "object": "chat.completion",
  "tools_executed": [
    "search_events",
    "get_event_details"
  ],
  "usage": {
    "completion_tokens": 12,
    "prompt_tokens": 9,
    "total_tokens": 21
  }
}

授权

Authorization
string
header
必填

使用 Bearer 令牌的 API 密钥身份验证

请求体

application/json

对话补全请求(兼容 OpenAI)。

这是一个无状态的对话补全端点。若需要带有线程的有状态会话,请改用 Responses API。

model
必填

模型标识字符串(例如:"openai/gpt-5"、"anthropic/claude-3-5-sonnet")。

示例:

"openai/gpt-4o"

messages
必填

会话历史。可以是由消息对象组成的列表,也可以是一个字符串;当为字符串时,会被视为单条用户消息。

示例:
[
  {
    "content": "Hello, how are you?",
    "role": "user"
  }
]
input

是 Responses 风格的 input 字段的便捷别名。当省略 messages 时,用于直接提供用户的 prompt。

示例:

"Translate this paragraph into French."

temperature
number | null

用于采样的温度,取值范围为 0 到 2。较高的数值(例如 0.8)会让输出更加随机,较低的数值(例如 0.2)会让输出更集中、更具确定性。通常建议只调整此参数或“top_p”中的一个,而不要同时调整。

必填范围: 0 <= x <= 2
示例:

0

top_p
number | null

一种与基于 temperature 的采样相对应的替代方案称为 nucleus sampling(核采样)。在这种方法中,模型只会从累计概率质量为 top_p 的那部分 token 集合中进行选择。因此,当 top_p = 0.1 时,表示只考虑累计构成前 10% 概率质量的那些 token。通常建议只调节这个参数或 “temperature” 中的一个,而不要同时调节二者。

必填范围: 0 <= x <= 1
示例:

0.1

max_tokens
integer | null

在对话补全(chat completion)中允许生成的最大 token 数。可以通过该值来控制通过应用程序编程接口 API 生成文本的成本。该参数已弃用,请改用 max_completion_tokens,且它与 o-series 模型不兼容。

必填范围: x >= 1
示例:

100

presence_penalty
number | null

取值范围为 -2.0 到 2.0。正值会根据新 token 是否已经在当前文本中出现来对其进行惩罚,从而提高模型转向讨论新主题的概率。

必填范围: -2 <= x <= 2
示例:

-0.5

frequency_penalty
number | null

取值范围为 -2.0 到 2.0。正值会根据到目前为止文本中已有的词频,对新生成的 token 施加惩罚,从而降低模型逐字重复同一句话的概率。

必填范围: -2 <= x <= 2
示例:

-0.5

logit_bias
Logit Bias · object

控制特定 token 在补全结果中出现的可能性。接受一个 JSON 对象,其中键是 token id(字符串形式),值是介于 -100 到 100 之间的偏置值。该偏置会在采样前加到对应 token 的 logits 上;-1 到 1 之间的值会对被选中概率产生轻微影响,而像 -100 或 100 这样的值则分别几乎等同于禁止或强制某个 token。

示例:
{ "50256": -100 }
stop
string[] | null

不支持最新的推理模型 “o3” 和 “o4-mini”。

最多可指定 4 个停止序列,应用程序编程接口 API 在生成内容命中这些序列时会停止继续生成;返回的文本中不包含这些停止序列本身。

示例:
["\n", "END"]
thinking
ThinkingConfigDisabled · object

字段:

  • type(必填):Literal['disabled']
示例:
{ "budget_tokens": 2048, "type": "enabled" }
top_k
integer | null

Top-k 采样。Anthropic:参数原样透传。Google:会注入到 generationConfig.topK 中。

必填范围: x >= 0
示例:

40

system

系统级 prompt/说明文本。Anthropic:直接透传。Google:转换为 systemInstruction。OpenAI:从 messages 中提取。

示例:

"You are a helpful assistant."

instructions

instructions(Responses 风格)的便捷别名。如果同时提供,则其优先级高于 system,也高于 system 角色的 messages。

示例:

"You are a concise assistant."

generation_config
Generation Config · object

Google 的 generationConfig 对象,会与自动生成的配置合并,用于设置 Google 特定参数(candidateCount、responseMimeType 等)。

示例:
{
  "candidateCount": 2,
  "responseMimeType": "application/json"
}
safety_settings
Safety Settings · object[] | null

Google 安全策略(危害类别和阈值)。

示例:
[
  {
    "category": "HARM_CATEGORY_HARASSMENT",
    "threshold": "BLOCK_NONE"
  }
]
tool_config
Tool Config · object

Google 的 tool 配置(例如函数调用模式等)。

示例:
{
  "function_calling_config": { "mode": "ANY" }
}
disable_automatic_function_calling
boolean | null

仅适用于 Google 模型的标志,用于禁用 SDK 的自动函数执行。设为 true 时,模型会返回需要由 Client 手动执行的函数调用。

示例:

true

seed
integer | null

如果指定该参数,系统会尽最大努力以确定性的方式进行采样。但对于相同的 seed,在不同的模型或应用程序编程接口 API 版本之间,并不保证结果完全一致。

示例:

42

user
string | null

用于标识终端用户的稳定标识符。可帮助 OpenAI 发现并防止滥用行为,并可能提升缓存命中率。该字段正逐步被“safety_identifier”和“prompt_cache_key”所取代。

示例:

"user-123"

n
integer | null

为每条输入消息生成多少个对话补全候选项。将参数 n 设为 1 可以将成本降到最低。

必填范围: 1 <= x <= 128
示例:

1

stream
boolean
默认值:false

如果为 true,则在生成过程中通过 Server-Sent Events 以流式传输方式将模型响应发送给 Client。

示例:

true

false

stream_options
Stream Options · object

流式传输响应的配置选项。仅在 stream 为 true 时设置(支持 include_usage 和 include_obfuscation)。

示例:
{ "include_usage": true }
response_format
Response Format · object

一个对象,用于指定模型必须输出的格式。对于结构化输出,使用 {'type': 'json_schema', 'json_schema': {...}};对于旧版 JSON 模式,使用 {'type': 'json_object'}。目前只有名称以 OpenAI 为前缀的模型会遵循该字段;如果在 Anthropic 或 Google 的请求中提供该字段,将会返回 invalid_request_error。

示例:
{ "type": "text" }
tools
Tools · object[] | null

模型可用的工具列表。支持 OpenAI 函数工具和自定义工具;对于 Dedalus 托管的服务端工具,请使用 mcp_servers

示例:
[
  {
    "function": {
      "description": "获取某个位置的当前天气",
      "name": "get_weather",
      "parameters": {
        "properties": {
          "location": { "description": "城市名称", "type": "string" }
        },
        "required": ["location"],
        "type": "object"
      }
    },
    "type": "function"
  }
]
tool_choice

控制模型将调用哪个工具(如果要调用的话)。none 会禁用工具调用,auto 由模型自行决定,required 会强制至少进行一次工具调用。指定具体的工具负载则会强制调用该工具。

示例:

"auto"

parallel_tool_calls
boolean | null

是否在工具调用时启用并行函数调用。

示例:

true

functions
Functions · object[] | null

已弃用,请改用 tools。这是旧版的函数定义列表,模型会基于其中的函数生成对应的 JSON 输入。

function_call

已弃用,请改用 tool_choice。用于控制模型调用哪个函数(none、auto 或指定的函数名)。

logprobs
boolean | null

是否返回输出 token 的对数概率(log probabilities)。如果为 true,则会在响应中返回每个 token 的对数概率。

示例:

true

top_logprobs
integer | null

一个介于 0 和 20 之间的整数,用于指定每个位置要返回的最高概率 token 的数量,并附带其对数概率。仅当 logprobs 设为 true 时生效。

必填范围: 0 <= x <= 20
示例:

5

max_completion_tokens
integer | null

对单次补全请求可生成的 token 总数设置上限,包括最终可见输出和用于推理的内部 token。

必填范围: x >= 1
示例:

1000

reasoning_effort
enum<string> | null

对支持推理的推理模型施加推理开销约束。更高的取值会消耗更多算力,通常可以提升推理质量,但会增加延迟和 token 用量。

可用选项:
low,
medium,
high
示例:

"medium"

audio
Audio · object

音频输出的参数。在请求音频响应时必填(例如 modalities 中包含 "audio" 时)。

示例:
{ "format": "mp3", "voice": "alloy" }
modalities
string[] | null

期望由模型生成的输出类型。大多数模型默认仅支持 ['text'];部分模型同时支持 ['text', 'audio']。

示例:
["text"]
prediction
Prediction · object

针对预测输出的配置。当你已经知道响应内容中大部分固定片段时,可以借此提升响应速度。

metadata
Metadata · object

最多包含 16 个键值字符串对的集合,可附加到请求上作为结构化元数据。

示例:
{ "session": "abc", "user_id": "123" }
store
boolean | null

是否将此聊天补全请求的输出保存下来,用于 OpenAI 的 model 蒸馏或评估产品。启用存储后,超过 8MB 的图像输入将被丢弃。

示例:

true

service_tier
enum<string> | null

指定此请求使用的处理层级。auto 使用项目默认配置,而 default 则强制采用标准价格和性能。

可用选项:
auto,
default
示例:

"auto"

prompt_cache_key
string | null

由 OpenAI 用于缓存相似请求的响应,以优化缓存命中率。用于替代旧版为缓存目的而使用的 user 字段。

safety_identifier
string | null

用于帮助识别可能违反 OpenAI 使用政策的用户的稳定标识符。建议在发送前先对终端用户标识符进行哈希处理。

verbosity
enum<string> | null

用于限制模型回复的详细程度。较低的取值会生成更精炼的回答,较高的取值则允许提供更多细节。

可用选项:
low,
medium,
high
web_search_options
Web Search Options · object

用于配置 OpenAI 网页搜索工具的参数。详情参见:https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat。

search_parameters
Search Parameters · object

用于配置网页搜索数据获取的 xAI 专用参数。如果未设置,模型将不会获取任何数据。

deferred
boolean | null

xAI 专用参数。若设置为 true,请求将返回一个 request_id,之后可以通过 GET /v1/chat/deferred-completion/{request_id} 异步获取完成结果。

mcp_servers

用于在服务器端执行 tool 的模型上下文协议(MCP)服务器地址。每一项可以是一个 URL(例如:https://mcp.example.com)、一个 slug(例如:dedalus-labs/brave-search),或者一个包含 slug/version/url 的结构化对象。这些 MCP tool 在服务器端执行,并单独计费。

示例:
[
  "dedalus-labs/brave-search",
  "dedalus-labs/github-api"
]
guardrails
Guardrails · object[] | null

应用于智能体的防护机制,用于进行输入/输出校验和安全检查。该功能保留供将来使用——guardrails 的配置格式尚未最终确定。

handoff_config
Handoff Config · object

用于多模型切换和智能体编排的配置。目前为预留功能,交接配置的具体格式尚未最终确定。

model_attributes
Model Attributes · object

用于在多模型执行过程中做路由决策的各个模型属性。格式:{'model_name': {'attribute': value}},其中 value 的取值范围为 0.0–1.0。常见属性包括:'intelligence'(智能)、'speed'(速度)、'cost'(成本)、'creativity'(创造力)、'accuracy'(准确性)。智能体会根据这些属性按任务需求选择最合适的模型。

示例:
{
  "anthropic/claude-3-5-sonnet": {
    "cost": 0.7,
    "creativity": 0.8,
    "intelligence": 0.95
  },
  "openai/gpt-4": {
    "cost": 0.8,
    "intelligence": 0.9,
    "speed": 0.6
  },
  "openai/gpt-4o-mini": {
    "cost": 0.2,
    "intelligence": 0.7,
    "speed": 0.9
  }
}
agent_attributes
Agent Attributes · object

针对智能体本身的属性偏好,用于影响其行为策略和模型选择。格式:{'attribute': value},其中 value 的取值范围为 0.0–1.0。常见属性包括:'complexity'(复杂度)、'accuracy'(准确性)、'efficiency'(效率)、'creativity'(创造力)、'friendliness'(友好度)。数值越高,表示对该特性的偏好或权重越高。

示例:
{
  "accuracy": 0.9,
  "complexity": 0.8,
  "efficiency": 0.7
}
max_turns
integer | null

在终止执行前,智能体可运行的最大迭代轮数(默认:10)。每一轮代表一次完整的模型推理循环。更大的取值允许更复杂的推理过程,但会增加成本和延迟。

必填范围: 1 <= x <= 100
示例:

5

auto_execute_tools
boolean
默认值:true

当其为 False 时,将跳过在服务端执行工具,而是在响应中直接返回原始的 OpenAI 风格 tool_calls。

示例:

true

false

响应

包含 ChatCompletionChunk 事件的 JSON 流或服务器发送事件 (SSE) 流

Dedalus 应用程序编程接口 API 的对话补全响应。

与 OpenAI 的对话补全响应兼容,并包含 Dedalus 扩展。 在保持与 OpenAI 应用程序编程接口 API 完全兼容的前提下,额外提供了诸如服务端 tool 执行跟踪和 模型上下文协议 (MCP) 错误报告等功能。

id
string
必填

用于标识该对话补全结果的唯一标识符。

choices
Choice · object[]
必填

对话补全候选列表。如果参数 n 大于 1,则可能包含多个候选项。

created
integer
必填

创建该对话补全结果时的 Unix 时间戳(单位:秒)。

model
string
必填

用于生成该对话补全结果的模型。

object
string
必填

对象类型,固定为 chat.completion

Allowed value: "chat.completion"
service_tier
enum<string> | null

指定用于处理此请求的服务层级。

  • 如果设置为 auto,请求将按照「项目设置」中配置的服务层级进行处理。除非另有配置,项目默认使用 default
  • 如果设置为 default,请求将以所选模型的标准价格和性能进行处理。
  • 如果设置为 flexpriority,请求将使用相应的服务层级进行处理。
  • 如果未设置,则默认行为为 auto

当设置了 service_tier 参数时,响应体中会包含一个 service_tier 字段,用于表示实际用于处理该请求的服务层级。该字段的值可能与请求参数中指定的值不同。

可用选项:
auto,
default,
flex,
scale,
priority
system_fingerprint
string

此指纹表示模型运行时所使用的后端配置。

可与请求参数 seed 配合使用,用来判断后端配置是否发生了可能影响结果确定性的变更。

usage
CompletionUsage · object

此补全请求的使用统计信息。

tools_executed
string[] | null

在服务器端实际执行过的工具名称列表(例如模型上下文协议 (MCP) 工具)。仅当工具在服务器端执行、而不是返回给客户端自行执行时才会出现。

mcp_server_errors
Mcp Server Errors · object

MCP 服务器在处理该请求期间(如果有)发生的故障信息。包括哪些服务器出错、具体原因,以及给用户的处理建议。仅在实际发生 MCP 服务器故障时才会返回。