---
url: 'https://dxpr.com/ko/hc/documentation/learn-dxpr-builder/ai/api-reference'
title: 'AI API 레퍼런스 | DXPR'
author:
  name: Jurriaan
  url: 'https://dxpr.com/users/jurriaan'
date: '2026-10-24T01:40:32+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-24T01:40:32+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/ko/hc/documentation/learn-dxpr-builder/ai/api-reference'
      articleSection: 'Architectuur en API’s'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/ko/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/ko'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: ko
---
[Help Center](/ko/node/75)/[Documentation](/ko/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 모델과 공급자](/ko/hc/documentation/learn-dxpr-builder/ai/models-and-providers)
- [AI 설정](/ko/hc/documentation/learn-dxpr-builder/ai/configuration)
- [AI 문제 해결](/ko/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 세션 쿠키 | 사용자별로 실행되는 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` | string | 아니요 | 기본값: `kavya-m1`. 공급자의 Allowed models 목록에 있어야 함 |
| `stream` | boolean | 아니요 | 기본값: `true` |
| `prediction` | object | 아니요 | 그대로 전달. 예: `{"type":"content","content":"<p>...</p>"}` |
| `providers` | string | 아니요 | 쉼표로 구분된 공급자 ID. 예: `openai,mistral` |
| `allowed_html_tags` | string | 아니요 | 그대로 전달. 빌더가 전송: `Bootstrap 5 HTML` |
| `allowed_html_classes` | string | 아니요 | 그대로 전달. 빌더가 전송: `Bootstrap 5 Classes` |
| `web_search` | boolean | 아니요 | 다음만 전달됩니다: `false`. |
| `response_format` | object | 아니요 | 그대로 전달. 예: `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`(이)가 허용 모델 목록에 없을 때 반환됨 |
| `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` | string | 예 | 이미지의 텍스트 설명 |
| `model` | string | 아니요 | 기본값: `kavya-image` |
| `size` | string | 아니요 | 빌더는 `1024x1024`, `1536x1024`, `1024x1536` 중 전송. Auto에서는 생략 |
| `quality` | string | 아니요 | 공급자에 그대로 전달됨 |
| `background` | string | 아니요 | 공급자에 그대로 전달됨 |

### 응답

`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` | string | 예 | 편집 지시 |
| `image` | string | 예 | 접두사 없는 Base64 이미지 데이터: `data:`. 엄격한 디코딩 |
| `mimeType` | string | 아니요 | 기본값: `image/png`. 서브타입이 파일 확장자가 됨 |
| `model` | string | 아니요 | 기본값: `kavya-image` |
| `size`, `quality`, `background` | string | 아니요 | 이미지 생성과 동일 |

### 응답

이미지 생성과 같은 형태: `{"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자)과 alt 속성이 됩니다.

## 다음 단계

- [모델 및 공급자](/ko/hc/documentation/learn-dxpr-builder/ai/models-and-providers)
- [AI 설정](/ko/hc/documentation/learn-dxpr-builder/ai/configuration)
- [AI 문제 해결](/ko/hc/documentation/learn-dxpr-builder/ai/troubleshooting)