---
url: 'https://dxpr.com/it/hc/documentazione/impara-dxpr-builder/ai/riferimento-api'
title: 'Riferimento API AI | DXPR'
author:
  name: Jurriaan
  url: 'https://dxpr.com/users/jurriaan'
date: '2026-10-24T03:04:13+00:00'
updated: '2026-10-24T17:19:22+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: |-
  DXPR Builder espone tre route AI. Il browser
  le chiama, e i controller delegano la richiesta
  tramite il modulo Drupal AI al provider DXPR
  (ai_provider_dxpr), così la chiave API non raggiunge
  mai il browser. Le route sono definite in
  dxpr_builder.routing.yml; il comportamento sotto viene
  da src/Controller/AiChatController.php e
  src/Controller/AiImageController.php.
tags:
  - 'Architecture and APIs'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-24T17:19:22+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'Riferimento API AI'
      description: |-
        DXPR Builder espone tre route AI. Il browser
        le chiama, e i controller delegano la richiesta
        tramite il modulo Drupal AI al provider DXPR
        (ai_provider_dxpr), così la chiave API non raggiunge
        mai il browser. Le route sono definite in
        dxpr_builder.routing.yml; il comportamento sotto viene
        da src/Controller/AiChatController.php e
        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-24T03:04:13+0000'
      dateModified: '2026-10-24T17:19:22+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/it/hc/documentazione/impara-dxpr-builder/ai/riferimento-api'
      articleSection: 'Architettura e API'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/it/hc/documentazione/impara-dxpr-builder/ai/riferimento-api'
      description: |-
        DXPR Builder espone tre route AI. Il browser
        le chiama, e i controller delegano la richiesta
        tramite il modulo Drupal AI al provider DXPR
        (ai_provider_dxpr), così la chiave API non raggiunge
        mai il browser. Le route sono definite in
        dxpr_builder.routing.yml; il comportamento sotto viene
        da src/Controller/AiChatController.php e
        src/Controller/AiImageController.php.
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: Home
            item: 'https://dxpr.com/it'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: it
---
[Centro assistenza](/it/hc)/[Documentazione](/it/hc/documentazione) /[Impara DXPR Builder](/it/hc/documentation/learn-dxpr-builder) /[Estendi](/it/hc/documentation/learn-dxpr-builder/extend) /[Architettura e API](/it/hc/documentation/learn-dxpr-builder/extend/architecture) # Riferimento API AI.

 Impara DXPR BuilderEstendiArchitettura e API

   ## In questa guida

 Guide correlate

- [Modelli e provider AI](/it/hc/documentazione/impara-dxpr-builder/ai/modelli-e-provider)
- [Configurazione AI](/it/hc/documentazione/impara-dxpr-builder/ai/configurazione)
- [Risoluzione dei problemi AI](/it/hc/documentazione/impara-dxpr-builder/ai/risoluzione-problemi)

DXPR Builder espone tre route AI. Il browser le chiama, e i controller delegano la richiesta tramite il modulo Drupal AI al provider DXPR (`ai_provider_dxpr`), così la chiave API non raggiunge mai il browser. Le route sono definite in `dxpr_builder.routing.yml`; il comportamento sotto viene da `src/Controller/AiChatController.php` e `src/Controller/AiImageController.php`.

## Requisiti di accesso (tutte e tre le route)

| Requisito | Origine |
|---|---|
| Metodo HTTP `POST` | `methods: [POST]` nella route |
| Permesso `edit with dxpr builder` | `_permission` |
| Utente fatturabile (posto di licenza valido) | `_dxpr_builder_billable_user`, verificato da `DxprBuilderBillableUserAccessCheck` |
| Token CSRF in `token` come parametro di query | `_csrf_token: 'TRUE'` |
| Cookie di sessione Drupal di utente collegato | I controlli di accesso Drupal girano per utente |

Il token è il token CSRF di route di Drupal per il percorso della route. DXPR Builder lo genera lato server e lo incorpora in `drupalSettings.dxprBuilder.aiAgent`come `endpointUrl`, `imageEndpointUrl` e `imageEditEndpointUrl` (vedi `DxprBuilderFormatter`). Leggi uno di quei valori da una pagina dove l’editor è caricato per ottenere un URL funzionante. Un controllo di accesso fallito restituisce la risposta `403` standard di Drupal.

I controller istanziano sempre il provider `dxpr`; il provider impostato in `/admin/config/ai/settings` non è usato.

## Chat

`POST /dxpr_builder/ajax/ai/chat?token=...`

Usata da comandi di testo, creazione pagine e suggerimenti di prompt. Il controller legge un corpo JSON e chiama `$provider->chat()`.

### Corpo della richiesta

| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
| `messages` | array di `{role, content}` | sì | `role` è `system`, `user` o `assistant` |
| `model` | stringa | no | Predefinito `kavya-m1`. Deve essere nell’elenco Allowed models del provider |
| `stream` | booleano | no | Predefinito `true` |
| `prediction` | oggetto | no | Passato attraverso, ad esempio `{"type":"content","content":"<p>...</p>"}` |
| `providers` | stringa | no | ID provider separati da virgole, ad esempio `openai,mistral` |
| `allowed_html_tags` | stringa | no | Passato attraverso; il builder invia `Bootstrap 5 HTML` |
| `allowed_html_classes` | stringa | no | Passato attraverso; il builder invia `Bootstrap 5 Classes` |
| `web_search` | booleano | no | Solo `false` è inoltrato |
| `response_format` | oggetto | no | Passato attraverso, ad esempio un `json_schema` come oggetto |

Il controller aggiunge sempre `jsonrpc: false` alla configurazione del provider. Prima della chiamata unisce i domini da **AI Output Filtering &gt; Allowed domains** nel filtro hostname del modulo AI per la durata della richiesta (`*` passa il filtro a piena fiducia).

### Risposta

In streaming (`stream` true, il predefinito): `200`, `Content-Type: text/event-stream`. Ogni evento è `data: {json}` seguito da una riga vuota, e lo stream finisce con `data: [DONE]`.

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

data: [DONE]

```

`id`, `object`, `created`, `model`, `original_model` e `usage` sono copiati dal chunk grezzo del provider quando presenti.

Non in streaming (`stream` false): `200`, `application/json`:

```json
{"choices":[{"message":{"role":"assistant","content":"..."}}]}

```

### Errori

| Stato | Corpo |
|---|---|
| `400` | Testo semplice `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."}}` quando `ai_provider_dxpr` è installato e `model` non è nel suo elenco Allowed models |
| `500` | `{"error":{"message":"The request could not be completed."}}` (dettagli nel canale di log `dxpr_builder`) |

### Esempio

```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);

```

## Generazione di immagini

`POST /dxpr_builder/ajax/ai/image?token=...`

Chiama `$provider->textToImage()`.

### Corpo della richiesta

| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
| `prompt` | stringa | sì | Descrizione testuale dell’immagine |
| `model` | stringa | no | Predefinito `kavya-image` |
| `size` | stringa | no | Il builder invia `1024x1024`, `1536x1024` o `1024x1536`; omesso per Auto |
| `quality` | stringa | no | Passato al provider invariato |
| `background` | stringa | no | Passato al provider invariato |

### Risposta

`200`, `application/json`. Solo la prima immagine è restituita, codificata base64. Il provider DXPR richiede output `webp`.

```json
{"data":[{"b64_json":"UklGRi..."}]}

```

### Errori

| Stato | Corpo |
|---|---|
| `400` | `{"error":{"message":"Invalid request: prompt required"}}` |
| `500` | `{"error":{"message":"No image was generated"}}` |
| `500` | `{"error":{"message":"Image generation failed. Please try again."}}` |

### Esempio

```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"}'

```

## Modifica delle immagini

`POST /dxpr_builder/ajax/ai/image/edit?token=...`

Chiama `$provider->imageToImage()` con l’immagine caricata e il prompt.

### Corpo della richiesta

| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
| `prompt` | stringa | sì | Istruzione di modifica |
| `image` | stringa | sì | Dati immagine Base64 senza prefisso `data:`; decodifica rigida |
| `mimeType` | stringa | no | Predefinito `image/png`; il sottotipo diventa l’estensione del file |
| `model` | stringa | no | Predefinito `kavya-image` |
| `size`, `quality`, `background` | stringa | no | Come per la generazione di immagini |

### Risposta

Stessa forma della generazione di immagini: `{"data":[{"b64_json":"..."}]}`.

### Errori

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

### Esempio

```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();

```

## Memorizzare un’immagine generata

Le route restituiscono solo byte di immagine. Il builder converte `b64_json` in un file `webp` e lo carica su `POST /dxpr_builder/ajax/file_upload`(`drupalSettings.dxprBuilder.fileUploadUrl`, campo form `upload[]`), che risponde con `url` e `fid` del file. Il prompt diventa il nome del file (primi 80 caratteri) e l’attributo alt.

## Prossimi passi

- [Modelli e provider AI](/it/hc/documentazione/impara-dxpr-builder/ai/modelli-e-provider)
- [Configurazione AI](/it/hc/documentazione/impara-dxpr-builder/ai/configurazione)
- [Risoluzione dei problemi AI](/it/hc/documentazione/impara-dxpr-builder/ai/risoluzione-problemi)