Dokumentacja API AI.

Poznaj DXPR BuilderRozszerzeniaArchitektura i API

Kreator DXPR udostępnia trzy trasy AI. Przeglądarka je wywołuje, a kontrolery przekazują żądanie przez drupalowy moduł AI do dostawcy DXPR (ai_provider_dxpr), więc klucz API nigdy nie dociera do przeglądarki. Trasy zdefiniowano w dxpr_builder.routing.yml; zachowanie poniżej pochodzi z src/Controller/AiChatController.php i src/Controller/AiImageController.php.

Panel generowania treści z promptem Add a paragraph with 3 feature boxes, linkami Enhance prompt i Chat mode, przyciskiem Generate content oraz przyciskami Choose a template i Add Elements

Wymagania dostępu (wszystkie trzy trasy)

Wymaganie Źródło
Metoda HTTP POST methods: [POST] w trasie
Uprawnienie edit with dxpr builder _permission
Użytkownik rozliczany (ważne miejsce licencyjne) _dxpr_builder_billable_user, sprawdzane przez DxprBuilderBillableUserAccessCheck
Token CSRF w token w parametrze zapytania _csrf_token: 'TRUE'
Ciasteczko zalogowanej sesji Drupala Kontrole dostępu Drupala działają dla użytkownika

Token to drupalowy token CSRF trasy dla ścieżki trasy. Kreator DXPR generuje go po stronie serwera i osadza w drupalSettings.dxprBuilder.aiAgent jako endpointUrl, imageEndpointUrl i imageEditEndpointUrl (zobacz DxprBuilderFormatter). Odczytaj jedną z tych wartości ze strony z wczytanym edytorem, aby uzyskać działający URL. Nieudana kontrola dostępu zwraca standardową odpowiedź 403 Drupala.

Kontrolery zawsze tworzą instancję dostawcy dxpr; dostawca ustawiony w /admin/config/ai/settings nie jest używany.

Czat

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

Używane przez polecenia tekstowe, tworzenie stron i sugestie promptów. Kontroler odczytuje treść JSON i wywołuje $provider->chat().

Treść żądania

Pole Typ Wymagane Uwagi
messages tablica {role, content} tak role to system, user albo assistant
model ciąg nie Domyślnie kavya-m1. Musi być na liście dozwolonych modeli dostawcy
stream wartość logiczna nie Domyślnie true
prediction obiekt nie Przekazywane dalej, na przykład {"type":"content","content":"<p>...</p>"}
providers ciąg nie Identyfikatory dostawców po przecinku, na przykład openai,mistral
allowed_html_tags ciąg nie Przekazywane dalej; kreator wysyła Bootstrap 5 HTML
allowed_html_classes ciąg nie Przekazywane dalej; kreator wysyła Bootstrap 5 Classes
web_search wartość logiczna nie Tylko false jest przekazywane dalej
response_format obiekt nie Przekazywane dalej, na przykład obiekt json_schema w treści

Kontroler zawsze dodaje jsonrpc: false do konfiguracji dostawcy. Przed wywołaniem scala domeny z AI Output Filtering > Allowed domains do filtra nazw hostów modułu AI na czas żądania (* przełącza filtr na pełne zaufanie).

Odpowiedź

Strumieniowana (stream true, domyślnie): 200, Content-Type: text/event-stream. Każde zdarzenie to data: {json} z pustym wierszem, a strumień kończy data: [DONE].

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

data: [DONE]

id, object, created, model, original_model i usage kopiowane są z surowego fragmentu dostawcy, gdy występują.

Niestrumieniowana (stream false): 200, application/json:

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

Błędy

Status Treść
400 Zwykły tekst 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."}}, gdy ai_provider_dxpr jest zainstalowany i nie ma model na liście dozwolonych modeli
500 {"error":{"message":"The request could not be completed."}} (szczegóły w kanale dziennika dxpr_builder)

Przykład

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

Generowanie obrazów

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

Wywołuje $provider->textToImage().

Treść żądania

Pole Typ Wymagane Uwagi
prompt ciąg tak Tekstowy opis obrazu
model ciąg nie Domyślnie kavya-image
size ciąg nie Kreator wysyła 1024x1024, 1536x1024 albo 1024x1536; pomijane dla Auto
quality ciąg nie Przekazywane do dostawcy bez zmian
background ciąg nie Przekazywane do dostawcy bez zmian

Odpowiedź

200, application/json. Zwracany jest tylko pierwszy obraz, zakodowany base64. Dostawca DXPR żąda wyniku webp.

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

Błędy

Status Treść
400 {"error":{"message":"Invalid request: prompt required"}}
500 {"error":{"message":"No image was generated"}}
500 {"error":{"message":"Image generation failed. Please try again."}}

Przykład

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

Edycja obrazów

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

Wywołuje $provider->imageToImage() z przesłanym obrazem i promptem.

Treść żądania

Pole Typ Wymagane Uwagi
prompt ciąg tak Instrukcja edycji
image ciąg tak Dane obrazu base64 bez prefiksu data:; ścisłe dekodowanie
mimeType ciąg nie Domyślnie image/png; podtyp staje się rozszerzeniem pliku
model ciąg nie Domyślnie kavya-image
size, quality, background ciąg nie Jak przy generowaniu obrazów

Odpowiedź

Kształt jak przy generowaniu obrazów: {"data":[{"b64_json":"..."}]}.

Błędy

Status Treść
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."}}

Przykład

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

Zapisywanie wygenerowanego obrazu

Trasy zwracają tylko bajty obrazu. Kreator konwertuje b64_json do pliku webp i przesyła go do POST /dxpr_builder/ajax/file_upload (drupalSettings.dxprBuilder.fileUploadUrl, pole formularza upload[]), które odpowiada z adresem url pliku i fid. Prompt staje się nazwą pliku (pierwsze 80 znaków) i atrybutem alt.

Co dalej?