---
url: 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/ai/api-reference'
title: 'AI API 参考 | DXPR'
author:
  name: Jurriaan
  url: 'https://dxpr.com/users/jurriaan'
date: '2026-10-24T00:45:35+00:00'
updated: '2026-10-24T09:09:48+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: 'DXPR Builder 开放三个 AI 路由。浏览器调用它们，控制器通过 Drupal AI 模块将请求代理到 DXPR 提供方（ai_provider_dxpr），因此 API 密钥从不到达浏览器。路由定义在 dxpr_builder.routing.yml 中；下文行为来自 src/Controller/AiChatController.php 和 src/Controller/AiImageController.php。'
tags:
  - 'Architectuur en API’s'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-24T09:09:48+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'AI API 参考'
      description: 'DXPR Builder 开放三个 AI 路由。浏览器调用它们，控制器通过 Drupal AI 模块将请求代理到 DXPR 提供方（ai_provider_dxpr），因此 API 密钥从不到达浏览器。路由定义在 dxpr_builder.routing.yml 中；下文行为来自 src/Controller/AiChatController.php 和 src/Controller/AiImageController.php。'
      image:
        '@type': ImageObject
        url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
        width: '1200'
        height: '630'
      datePublished: '2026-10-24T00:45:35+0000'
      dateModified: '2026-10-24T09:09:48+0000'
      author:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      mainEntityOfPage: 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/ai/api-reference'
      articleSection: 'Architectuur en API’s'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/ai/api-reference'
      description: 'DXPR Builder 开放三个 AI 路由。浏览器调用它们，控制器通过 Drupal AI 模块将请求代理到 DXPR 提供方（ai_provider_dxpr），因此 API 密钥从不到达浏览器。路由定义在 dxpr_builder.routing.yml 中；下文行为来自 src/Controller/AiChatController.php 和 src/Controller/AiImageController.php。'
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: 首页
            item: 'https://dxpr.com/zh-hans'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: zh-hans
---
[Help Center](/zh-hans/node/75)/[Documentation](/zh-hans/hc/documentation) /[Learn DXPR Builder](/hc/documentation/learn-dxpr-builder) /[Extend](/hc/documentation/learn-dxpr-builder/extend) /[Architectuur en API’s](/hc/documentation/learn-dxpr-builder/extend/architecture) # AI API 参考.

 Learn DXPR BuilderExtendArchitectuur en API’s

   ## In this guide

 Related guides

- [AI 模型和服务商](/zh-hans/hc/documentation/learn-dxpr-builder/ai/models-and-providers)
- [AI 配置](/zh-hans/hc/documentation/learn-dxpr-builder/ai/configuration)
- [AI 故障排查](/zh-hans/hc/documentation/learn-dxpr-builder/ai/troubleshooting)

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 &gt; Allowed domains** 的域名并入 AI 模块的主机名过滤器，持续时间为本次请求（`*` 将过滤器切换为完全信任）。

### 响应

流式（`stream` 为 true，默认）：`200`，`Content-Type: text/event-stream`。每个事件是 `data: {json}` 加一个空行，流以 `data: [DONE]` 结束。

```text
data: {"choices":[{"delta":{"content":"Hello"}}],"id":"...","model":"kavya-m1","usage":{...}}

data: [DONE]

```

`id`、`object`、`created`、`model`、`original_model` 和 `usage` 在提供方原始分块中有即照抄。

非流式（`stream` 为 false）：`200`，`application/json`：

```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` 日志通道中） |

### 示例

```js
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` 输出。

```json
{"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."}}` |

### 示例

```bash
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."}}` |

### 示例

```js
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 个字符）和替代文本。

## 接下来做什么？

- [模型和服务商](/zh-hans/hc/documentation/learn-dxpr-builder/ai/models-and-providers)
- [AI 配置](/zh-hans/hc/documentation/learn-dxpr-builder/ai/configuration)
- [AI 故障排查](/zh-hans/hc/documentation/learn-dxpr-builder/ai/troubleshooting)