Entwickeln / Referenz
Bilder
Erzeugt Bilder aus einem Text-Prompt im OpenAI-Format; das Gateway prüft Anzahl und Größe und leitet den Prompt unmaskiert weiter.
/v1/images/generations - Familie
- image_gen
- Maskierung
- nein
- Streaming
- nein
- Format
- JSON
- Abrechnung
- Bilder oder Megapixel
Anfrage
Das Gateway nimmt den Body im Format der OpenAI Images API an. model ist Pflicht und muss ein Modell der Familie image_gen aus GET /v1/models sein. Der Endpunkt nimmt nur POST an.
Das Gateway gibt die JSON-Antwort des Anbieters zurück. Bei den angebundenen Anbietern stehen die Bilddaten Base64-kodiert in data[].b64_json.
curl https://api.noirdoc.de/v1/images/generations \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "black-forest-labs/FLUX.1-schnell",
"prompt": "Ein Leuchtturm an der Nordsee bei Sonnenaufgang",
"size": "1024x1024",
"n": 1
}'import base64
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
response = client.images.generate(
model="black-forest-labs/FLUX.1-schnell",
prompt="Ein Leuchtturm an der Nordsee bei Sonnenaufgang",
size="1024x1024",
n=1,
)
with open("leuchtturm.png", "wb") as f:
f.write(base64.b64decode(response.data[0].b64_json))import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const response = await client.images.generate({
model: "black-forest-labs/FLUX.1-schnell",
prompt: "Ein Leuchtturm an der Nordsee bei Sonnenaufgang",
size: "1024x1024",
n: 1,
});
const png = Buffer.from(response.data![0].b64_json!, "base64");
fs.writeFileSync("leuchtturm.png", png);Grenzen
Das Gateway prüft diese Werte, bevor es die Anfrage weiterleitet. Verstöße beantwortet es mit 400 invalid_image_request.
| Feld | Regel |
|---|---|
prompt | nicht leerer String |
n | ganze Zahl von 1 bis 10, Standard 1 |
size | BREITExHÖHE, jede Seite 1 bis 2048 Pixel. Ohne size rechnet das Gateway mit 1024x1024. Werte wie auto lehnt es ab. |
| Gesamtgröße | n × Megapixel je Bild höchstens 16. Das Gateway rundet je Bild auf volle Einheiten von 1024 × 1024 Pixeln auf. |
Beispiele für die Gesamtgröße: 1024x1024 zählt eine Einheit, also sind bis zu zehn Bilder möglich. 2048x2048 zählt vier Einheiten, also höchstens vier Bilder. 1536x1024 zählt zwei Einheiten.
Viele Modelle erlauben engere Werte, etwa nur ein Bild pro Anfrage oder nur bestimmte Auflösungen. Lehnt der Anbieter die Anfrage ab, erhalten Sie seinen Statuscode und Body unverändert.
Was Noirdoc ändert
| Bereich | Verhalten |
|---|---|
| Modell | Das Gateway löst die Modell-ID über den Katalog auf und sendet dem Anbieter dessen eigenen Modellnamen. |
| Anbieter | Der Header X-Noirdoc-Provider in der Antwort nennt den Anbieter. Siehe Anbieter & Routing. |
| Streaming | Keines. "stream": true beantwortet das Gateway mit 400 streaming_not_supported_for_endpoint. |
| Abrechnung | Je nach Modell rechnet das Gateway pro Bild oder pro Megapixel ab. Es zählt die Bilder in data der Antwort. Die Größe nimmt es aus dem Feld size der Antwort, sonst aus der Anfrage, sonst 1024x1024. Die Preise nennt Modelle & Preise. |
| Header | Das Gateway entfernt Ihren Schlüssel und X-Noirdoc-Mask, bevor es die Anfrage weiterleitet. |
Unterrouten
Keine. Bildbearbeitung (/v1/images/edits) und andere Pfade unter /v1/images/ beantwortet das Gateway mit 404 unsupported_endpoint.
Fehler auf diesem Endpunkt
| Status | Code | Bedeutung |
|---|---|---|
| 400 | model_required | Die Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld). |
| 400 | wrong_endpoint_for_model | Das Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt. |
| 400 | streaming_not_supported_for_endpoint | Die Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht. |
| 400 | invalid_request_body | Der Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert. |
| 400 | invalid_image_request | prompt, n oder size liegt außerhalb der Grenzen des Gateways; message nennt den Parameter. |
| 402 | insufficient_credit | Das Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage. |
| 402 | key_budget_exhausted | Das Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus. |
| 403 | model_not_allowed_for_key | Das Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels. |
| 403 | provider_not_allowed_for_tenant | Die Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet. |
| 403 | provider_not_allowed_for_key | Die Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus. |
| 403 | masking_not_supported_for_endpoint | Der Endpunkt kann nicht maskieren, aber die Maskierungsrichtlinie ist enforced oder die Anfrage sendet X-Noirdoc-Mask: on. |
| 404 | model_not_available | Die Modell-ID ist für die Organisation nicht verfügbar. |
| 405 | method_not_allowed | Der Endpunkt nimmt nur POST an. |
| 502 | provider_unreachable | Das Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen. |
| 504 | provider_timeout | Der Anbieter hat nicht innerhalb der Wartezeit des Gateways geantwortet. |
OpenAI-Referenz
Alle übrigen Felder von Anfrage und Antwort beschreibt die API-Referenz von OpenAI: Images (geprüft am 30.09.2026).