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.

POST /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.

Shell
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
  }'
Python
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))
TypeScript
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.

FeldRegel
promptnicht leerer String
nganze Zahl von 1 bis 10, Standard 1
sizeBREITExHÖHE, jede Seite 1 bis 2048 Pixel. Ohne size rechnet das Gateway mit 1024x1024. Werte wie auto lehnt es ab.
Gesamtgrößen × 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

BereichVerhalten
ModellDas Gateway löst die Modell-ID über den Katalog auf und sendet dem Anbieter dessen eigenen Modellnamen.
AnbieterDer Header X-Noirdoc-Provider in der Antwort nennt den Anbieter. Siehe Anbieter & Routing.
StreamingKeines. "stream": true beantwortet das Gateway mit 400 streaming_not_supported_for_endpoint.
AbrechnungJe 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.
HeaderDas 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

StatusCodeBedeutung
400model_requiredDie Anfrage nennt kein Modell (model im Body, bei /v1/audio/transcriptions im Formularfeld).
400wrong_endpoint_for_modelDas Modell gehört zu einer anderen Endpunkt-Familie oder einem anderen API-Format als der aufgerufene Endpunkt.
400streaming_not_supported_for_endpointDie Anfrage verlangt Streaming, der Endpunkt unterstützt es aber nicht.
400invalid_request_bodyDer Body ist kein JSON-Objekt oder nicht in UTF-8 kodiert.
400invalid_image_requestprompt, n oder size liegt außerhalb der Grenzen des Gateways; message nennt den Parameter.
402insufficient_creditDas Guthaben der Organisation ist aufgebraucht oder kleiner als die geschätzten Höchstkosten der Anfrage.
402key_budget_exhaustedDas Budget dieses Schlüssels ist für den laufenden Zeitraum aufgebraucht oder reicht für die geschätzten Kosten der Anfrage nicht aus.
403model_not_allowed_for_keyDas Modell gehört nicht zu den erlaubten Modellen dieses Schlüssels.
403provider_not_allowed_for_tenantDie Organisation gilt als Berufsgeheimnisträger (§ 203 StGB); das schließt jeden Anbieter aus, der dieses Modell anbietet.
403provider_not_allowed_for_keyDie Einschränkungen des Schlüssels (Anbieter, Datenresidenz, CLOUD Act, § 203) schließen jeden Anbieter dieses Modells aus.
403masking_not_supported_for_endpointDer Endpunkt kann nicht maskieren, aber die Maskierungsrichtlinie ist enforced oder die Anfrage sendet X-Noirdoc-Mask: on.
404model_not_availableDie Modell-ID ist für die Organisation nicht verfügbar.
405method_not_allowedDer Endpunkt nimmt nur POST an.
502provider_unreachableDas Gateway konnte keine Verbindung zum Anbieter herstellen, oder die Verbindung ist abgebrochen.
504provider_timeoutDer 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).