AI API 参考.
DXPR Builder 开放三个 AI 路由。浏览器调用它们，控制器通过 Drupal AI 模块将请求代理到 DXPR 提供方（ai_provider_dxpr），因此 API 密钥从不到达浏览器。路由定义在 dxpr_builder.routing.yml 中；下文行为来自 src/Controller/AiChatController.php 和 src/Controller/AiImageController.php。
访问要求（三个路由通用）
| 要求 | 来源 |
|---|---|
HTTP 方法 POST |
methods: [POST]（路由中） |
权限 edit with dxpr builder |
_permission |
| 计费用户（有效许可证名额） | _dxpr_builder_billable_user，检查方为 DxprBuilderBillableUserAccessCheck |
查询参数 token 中的 CSRF 令牌 |
_csrf_token: 'TRUE' |
| 已登录的 Drupal 会话 Cookie | Drupal 按用户运行访问检查 |
令牌是该路由路径的 Drupal 路由 CSRF 令牌。DXPR Builder 在服务器端生成它，并嵌入 drupalSettings.dxprBuilder.aiAgent，为 endpointUrl、imageEndpointUrl 和 imageEditEndpointUrl（见 DxprBuilderFormatter）。从加载了编辑器的页面读取其中一个值，即可获得可用的 URL。访问检查失败返回 Drupal 标准的 403 响应。
控制器始终实例化 dxpr 提供方；/admin/config/ai/settings 设置的提供方不起作用。
聊天
POST /dxpr_builder/ajax/ai/chat?token=...
供文本命令、页面创建和提示建议使用。控制器读取 JSON 请求体并调用 $provider->chat()。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
messages |
数组 {role, content} |
是 | role 为 system、user 或 assistant |
model |
字符串 | 否 | 默认为 kavya-m1。必须在提供方的 Allowed models 列表中 |
stream |
布尔值 | 否 | 默认为 true |
prediction |
对象 | 否 | 透传，例如 {"type":"content","content":"<p>...</p>"} |
providers |
字符串 | 否 | 逗号分隔的提供方 ID，例如 openai,mistral |
allowed_html_tags |
字符串 | 否 | 透传；构建器发送 Bootstrap 5 HTML |
allowed_html_classes |
字符串 | 否 | 透传；构建器发送 Bootstrap 5 Classes |
web_search |
布尔值 | 否 | 只有 false 会转发 |
response_format |
对象 | 否 | 透传，例如 json_schema 对象 |
控制器总在提供方配置中添加 jsonrpc: false。调用前，它将 AI Output Filtering > Allowed domains 的域名并入 AI 模块的主机名过滤器，持续时间为本次请求（* 将过滤器切换为完全信任）。
响应
流式（stream 为 true，默认）：200，Content-Type: text/event-stream。每个事件是 data: {json} 加一个空行，流以 data: [DONE] 结束。
data: {"choices":[{"delta":{"content":"Hello"}}],"id":"...","model":"kavya-m1","usage":{...}}
data: [DONE]
id、object、created、model、original_model 和 usage 在提供方原始分块中有即照抄。
非流式（stream 为 false）：200，application/json：
{"choices":[{"message":{"role":"assistant","content":"..."}}]}
错误
| 状态 | 请求体 |
|---|---|
400 |
纯文本 Invalid request: messages required |
403 |
{"error":{"code":"model_not_allowed","message":"The selected model is not allowed. Please refresh the page to update your model options."}}（当安装了 ai_provider_dxpr 且 model 不在其 Allowed models 列表中时） |
500 |
{"error":{"message":"The request could not be completed."}}（详情在 dxpr_builder 日志通道中） |
示例
const url = drupalSettings.dxprBuilder.aiAgent.endpointUrl;
const res = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
model: "kavya-m1",
stream: false,
messages: [
{ role: "system", content: "You are a copywriter." },
{ role: "user", content: "Shorten: <p>Our team ...</p>" }
]
})
});
const data = await res.json();
console.log(data.choices[0].message.content);
图像生成
POST /dxpr_builder/ajax/ai/image?token=...
调用 $provider->textToImage()。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt |
字符串 | 是 | 图片的文本描述 |
model |
字符串 | 否 | 默认为 kavya-image |
size |
字符串 | 否 | 构建器发送 1024x1024、1536x1024 或 1024x1536；Auto 时省略 |
quality |
字符串 | 否 | 原样传给提供方 |
background |
字符串 | 否 | 原样传给提供方 |
响应
200，application/json。只返回第一张图片，base64 编码。DXPR 提供方请求 webp 输出。
{"data":[{"b64_json":"UklGRi..."}]}
错误
| 状态 | 请求体 |
|---|---|
400 |
{"error":{"message":"Invalid request: prompt required"}} |
500 |
{"error":{"message":"No image was generated"}} |
500 |
{"error":{"message":"Image generation failed. Please try again."}} |
示例
curl -X POST "https://example.com/dxpr_builder/ajax/ai/image?token=TOKEN" \
-H "Content-Type: application/json" \
-H "Cookie: SESSxxx=..." \
-d '{"prompt":"Flat illustration of a rocket","size":"1536x1024"}'
图像编辑
POST /dxpr_builder/ajax/ai/image/edit?token=...
用上传的图片和提示词调用 $provider->imageToImage()。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt |
字符串 | 是 | 编辑指令 |
image |
字符串 | 是 | Base64 图片数据，不带 data: 前缀；严格解码 |
mimeType |
字符串 | 否 | 默认为 image/png；子类型成为文件扩展名 |
model |
字符串 | 否 | 默认为 kavya-image |
size、quality、background |
字符串 | 否 | 同图像生成 |
响应
与图像生成形状相同：{"data":[{"b64_json":"..."}]}。
错误
| 状态 | 请求体 |
|---|---|
400 |
{"error":{"message":"Invalid request: prompt and image required"}} |
400 |
{"error":{"message":"Invalid image data: base64 decode failed"}} |
500 |
{"error":{"message":"No image was generated"}} |
500 |
{"error":{"message":"Image editing failed. Please try again."}} |
示例
const url = drupalSettings.dxprBuilder.aiAgent.imageEditEndpointUrl;
const res = await fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
prompt: "Remove the background",
image: base64String,
mimeType: "image/jpeg"
})
});
const { data } = await res.json();
存放生成的图片
路由只返回图片字节。构建器将 b64_json 转为 webp 文件，上传到 POST /dxpr_builder/ajax/file_upload（drupalSettings.dxprBuilder.fileUploadUrl，表单字段 upload[]），该地址返回文件的 url 和 fid。提示词成为文件名（前 80 个字符）和替代文本。