API zur Bildgenerierung

POST /v1/images/generations

Der Text-zu-Bild-Endpunkt verwendet einen Request-Body im Format application/json. Sende einen Prompt, halte den HTTP-Request geöffnet und lies jedes Bild aus data[].b64_json in derselben Antwort.

Verwende https://bettertoken.ai/v1 als Base URL. Übermittle deinen BetterToken API Key über Authorization: Bearer YOUR_API_KEY.

Du kannst Authorization und den Request-Body im Playground auf der rechten Seite eingeben und den Request dann direkt an https://bettertoken.ai/v1/images/generations senden.

Lege API Keys nicht in Browser-Frontend-Code, Git-Repositories, Tickets, Screenshots oder Logs ab. Speichere API Keys für serverseitige Proxy-Aufrufe nur in Server-Umgebungsvariablen oder einem Secret Manager.

Standbilder von gpt-image-2.6-flare und gpt-image-2.6-sunburst sind auf 1K begrenzt. GIF/SVG-Erzeugung und Bearbeitung mit Referenzbild sind verfügbar; abgerechnet wird pro Anfrage. Die Größentabellen und auflösungsabhängigen Abrechnungsbeispiele unten gelten für GPT Image 2 und 2.5. Anleitung für GPT Image 2.6

Passenden Ablauf wählen

• Ein Bild aus Text generieren und das Ergebnis speichern: Bleibe auf dieser Seite. Beginne mit dem curl-Beispiel und verwende anschließend Bild speichern, um alle Einträge in data[] zu dekodieren.
• Ein Bild bearbeiten: Lade ein oder mehrere Referenzbilder über die Bildbearbeitungs-API hoch. Für die normale Referenzbildbearbeitung ist keine Maske erforderlich; füge sie nur für eine lokale Bearbeitung hinzu, wenn das gewählte Modell und die Größe dies unterstützen.
• Modell und Parameter wählen und das Budget schätzen: Prüfe aktuelle Model IDs und Preise in der model plaza und verwende unten Empfohlene Werte für die Request-Parameter. Der GPT Image-Leitfaden erläutert den vollständigen Ablauf.

Schnellstart mit curl

Verwende https://bettertoken.ai/v1 als Base URL und sende einen Request an https://bettertoken.ai/v1/images/generations:

curl --max-time 300 -X POST "https://bettertoken.ai/v1/images/generations" \
  -o response.json \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A product photo of a green ceramic mug on a studio table",
    "size": "1024x1024",
    "n": 1,
    "response_format": "b64_json",
    "output_format": "png"
  }'

Empfohlene Werte

Dies sind Startwerte, keine festen Anforderungen. Beginne mit n=1; der Endpunkt akzeptiert Ganzzahlen von 1 bis 10, kann aber weniger Bilder zurückgeben.

{
  "model": "gpt-image-2",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}

Parameter	Zu sendender Wert	Zweck
model	gpt-image-2, gpt-image-2.5-flare oder gpt-image-2.5-sunburst	Wähle eine verfügbare Model ID aus der model plaza. Eine gültige ID garantiert nicht, dass Modell, Größe oder Vorgang für die Anfrage verfügbar sind.
prompt	Eine Textbeschreibung	Erforderlich. Beschreibe Motiv, Stil, Komposition und wichtige Einschränkungen.
size	Weglassen, auto oder Maße wie 1024x1024	Fordert Größe und Seitenverhältnis an; die gelieferten Maße können abweichen.
n	Ganzzahl von 1 bis 10	Maximale angeforderte Bildanzahl. Beginne mit 1; es können weniger Bilder zurückkommen.
quality	auto, low, medium, high für gpt-image-2; 2.5-Modelle akzeptieren zusätzlich xhigh und max	Optionale Qualitätspräferenz. Lasse das Feld weg oder sende JSON null für den Standardwert. Die Annahme garantiert keine bessere Bildqualität durch eine höhere Stufe.
response_format	b64_json	Gibt jedes Bild als Base64 in data[].b64_json zurück.
output_format	Zum Beispiel png	Angefordertes Format, keine Garantie für die Kodierung. Ermittle vor dem Speichern das tatsächliche Format anhand der Bytes.

Die Antwort kann weniger Bilder als n enthalten. Verarbeite alle Einträge in data[]; die Empfehlung n=1 ist keine Serverbegrenzung.

Empfohlene Größen

size	Verhältnis	Anwendungsfall
auto	Auto	Automatische Größenauswahl
1024x1024	1:1	Quadratische Bilder, Avatare, Cover, Assets
1536x1024	3:2	Querformat-Poster, Banner, Szenen
1024x1536	2:3	Mobile Cover und Poster im Hochformat
1536x1152	4:3	Standardbilder im Querformat, Produktbilder, Inhaltsgrafiken
1152x1536	3:4	Standardbilder im Hochformat, mobile Cover, vertikale Poster
2048x2048	1:1	Quadratische Bilder mit hoher Auflösung
2048x1152	16:9	Querformatbilder mit hoher Auflösung
3840x2160	16:9	4K-Querformatbilder
2160x3840	9:16	4K-Hochformatbilder

Die Tabellenwerte sind Beispiele, keine abschließende Liste. Du kannst size weglassen oder auto verwenden; JSON null aktiviert ebenfalls die automatische Auswahl. Explizite Breite und Höhe müssen positiv und durch 16 teilbar sein, jeweils höchstens 3840; das Seitenverhältnis darf 3:1 und die Gesamtpixelzahl muss 655360 bis 8294400 betragen. Auch 2080x2080 ist gültig. Die tatsächlichen Abmessungen können abweichen: Prüfe das Bild und schneide es nicht erzwungen zu.

Bild speichern

Eine erfolgreiche Antwort folgt dem OpenAI-kompatiblen Bildantwortformat. Die folgenden Beträge veranschaulichen das Belegformat und sind keine Festpreise:

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)",
      "revised_prompt": "Optional revised prompt"
    }
  ],
  "bettertoken_image_billing": {
    "currency": "CNY",
    "settled_amount": "0.15",
    "outputs": [
      {
        "index": 0,
        "width": 1254,
        "height": 1254,
        "billing_resolution": "2K",
        "currency": "CNY",
        "amount": "0.15"
      }
    ]
  }
}

Lies jedes data[].b64_json und berücksichtige zusätzliche Felder wie revised_prompt in deinem Client. BetterToken gibt Abrechnungsdetails im Stammobjekt bettertoken_image_billing zurück. settled_amount und outputs[].amount sind Dezimalstrings; outputs[].index beginnt bei 0.

output_format fordert ein Format an, garantiert aber weder die Kodierung noch eine Konvertierung. Prüfe die Bildbytes und verwende die passende Dateiendung.

import base64
import json
from pathlib import Path

result = json.loads(Path("response.json").read_text(encoding="utf-8"))
for index, item in enumerate(result["data"], start=1):
    encoded = item["b64_json"]
    if "," in encoded and "base64" in encoded.split(",", 1)[0]:
        encoded = encoded.split(",", 1)[1]
    image_bytes = base64.b64decode(encoded)
    if image_bytes.startswith(b"\x89PNG\r\n\x1a\n"):
        extension = "png"
    elif image_bytes.startswith(b"\xff\xd8\xff"):
        extension = "jpg"
    elif image_bytes.startswith(b"RIFF") and image_bytes[8:12] == b"WEBP":
        extension = "webp"
    else:
        raise ValueError("Unsupported image signature")
    Path(f"output-{index}.{extension}").write_bytes(image_bytes)

JavaScript-Beispiel (Node.js)

import { writeFile } from "node:fs/promises";

const response = await fetch("https://bettertoken.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "A green ceramic mug on a studio table",
    size: "1024x1024",
    n: 1,
    response_format: "b64_json",
    output_format: "png",
  }),
});

if (!response.ok) {
  throw new Error(await response.text());
}

const result = await response.json();
const { data } = result;
for (const [index, item] of data.entries()) {
  const b64Json = item.b64_json.replace(/^data:.*;base64,/, "");
  const imageBytes = Buffer.from(b64Json, "base64");
  let extension;
  if (imageBytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
    extension = "png";
  } else if (imageBytes[0] === 0xff && imageBytes[1] === 0xd8 && imageBytes[2] === 0xff) {
    extension = "jpg";
  } else if (imageBytes.toString("ascii", 0, 4) === "RIFF" && imageBytes.toString("ascii", 8, 12) === "WEBP") {
    extension = "webp";
  } else {
    throw new Error("Unsupported image signature");
  }
  await writeFile(`output-${index + 1}.${extension}`, imageBytes);
}

Wenn deine Anwendung eine feste PNG-, JPEG- oder WebP-Kodierung benötigt, bestimme zuerst das tatsächliche Format und konvertiere das Bild bei Bedarf. Eine geänderte Dateiendung allein konvertiert das Bild nicht.

Tatsächliche Kosten prüfen

bettertoken_image_billing wird mit dem Ergebnis zurückgegeben; eine separate Kostenabfrage ist nicht nötig.

Feld	Bedeutung
currency	Abrechnungswährung; nicht immer USD oder CNY.
settled_amount	Gesamtabrechnung der Anfrage als Dezimalzeichenfolge.
requested_resolution	Aus der Anfrage ermittelte Auflösungsstufe.
outputs[].index	Bei 0 beginnender Bildindex passend zu data[].
outputs[].width, height	Tatsächliche Breite und Höhe in Pixeln.
outputs[].billing_resolution	Endgültige Abrechnungsstufe des Bildes.
outputs[].currency, amount	Abrechnungswährung und Betrag pro Bild.

Angeforderte Größe und Abrechnungsstufe können abweichen: Eine Anfrage mit 1024x1024 lieferte 1254x1254 und wurde als 2K abgerechnet. Verwende den Belegbetrag und prüfe aktuelle Preise in der model plaza. Zeige Beträge als Zeichenfolgen an und rechne dezimal. Ein fehlender Beleg bedeutet nicht null Kosten.

from decimal import Decimal

billing = result.get("bettertoken_image_billing")
if billing is None:
    print("Billing receipt unavailable; check your usage records.")
else:
    total = Decimal(billing["settled_amount"])
    print(f"Total: {billing['currency']} {total}")
    for output in billing.get("outputs", []):
        print(
            f"Image {output['index'] + 1}: "
            f"{output['width']}x{output['height']}, "
            f"{output['billing_resolution']}, "
            f"{output['currency']} {output['amount']}"
        )

Antwortablauf

Dieser Endpunkt ist synchron. Halte nach dem Senden von POST /images/generations den aktuellen HTTP-Request offen, bis der Server antwortet. Bei Erfolg werden alle Bilder in data[].b64_json zurückgegeben.

Der Endpunkt gibt keine task_id zurück; es gibt keinen separaten Endpunkt für Statusabfragen oder das Herunterladen von Ergebnissen.

Vor der Verarbeitung kann BetterToken den höchsten anwendbaren Einzelpreis multipliziert mit n vorautorisieren. Das Guthaben kann für das gelieferte 1K-Bild ausreichen, aber nicht für diese Reservierung; dann wird die Anfrage mit 403 und error.code=insufficient_user_quota abgelehnt. Die endgültige Abrechnung basiert auf den tatsächlich gelieferten Bildern.

Timeouts und Wiederholungen

• Setze HTTP-Client-Timeouts auf mehrere Minuten.
• Bei einem Transportfehler oder mehrdeutigem Serverfehler kann unklar sein, ob die Anfrage ausgeführt und berechnet wurde. Sende nicht automatisch erneut; prüfe Verbrauch und Protokolle und speichere die Request-ID sowie empfangene Header X-BetterToken-Image-Receipt und X-BetterToken-Billing-State.
• Wiederhole Eingabe- und Authentifizierungsfehler, fehlende Parameter oder fehlerhafte Requests nicht automatisch.
• Wiederhole 429 nur mit Backoff, wenn die Ablehnung bestätigt wurde. Eine eigene Request-ID macht den Server nicht idempotent; es gibt keinen separaten Endpunkt zur Statusabfrage.

Fehlerbehandlung

Fehler geben gewöhnlich JSON zurück. Lies beim Anzeigen eines Fehlers zuerst error.message, dann message und anschließend den HTTP-Status-Text.

HTTP-Status	Bedeutung	Vorgehen
400	Fehlerhaftes JSON, fehlender Parameter oder nicht unterstützte Größe	Prüfe den Request-Body. Nicht automatisch wiederholen.
401	API Key fehlt oder ist ungültig	Prüfe den Header Authorization: Bearer YOUR_API_KEY.
402 oder 403	Guthaben oder Kontingent unzureichend	Prüfe error.code und das Kontingent. Bei 403 mit error.code=insufficient_user_quota reicht das Guthaben möglicherweise für das gelieferte Bild, aber nicht für die Vorautorisierung.
429	Ratenlimit, Parallelitätslimit oder ausgelasteter Upstream	Wiederhole nur nach bestätigter Ablehnung mit Backoff.
5xx	Gateway- oder Upstream-Fehler	Ausführung und Abrechnung können unbekannt sein. Prüfe Protokolle und Verbrauch, bevor du bewusst erneut sendest.

Integrations-Checkliste

• Die Base URL ist https://bettertoken.ai/v1.
• Der Header enthält Authorization: Bearer sk-....
• Die Anfrage verwendet application/json.
• Wähle eine für diese Anfrage verfügbare Model ID: gpt-image-2, gpt-image-2.5-flare oder gpt-image-2.5-sunburst.
• Verwende response_format=b64_json. output_format ist ein angeforderter Wert; erkenne vor dem Speichern das tatsächliche Format anhand der Bytes.
• n akzeptiert Ganzzahlen von 1 bis 10. Beginne mit 1; es können weniger Bilder zurückkommen.
• Lasse size weg, nutze auto oder gültige Abmessungen. Die Tabelle oben ist keine abschließende Liste.
• Der HTTP-Client erlaubt mehrere Minuten Wartezeit für die Generierung.
• Protokolle und Fehler-Screenshots legen weder den API Key noch den vollständigen Base64-Bildinhalt offen.

Verwandte Dokumentation

• Bild zu Bild
• GPT Image-Leitfaden
• GPT Image 2 ist verfügbar

POST/v1/images/generationsAusprobieren

Autorisierungen

Authorizationstringheadererforderlich

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body application/json

modelenum<string>Standard: gpt-image-2erforderlich

GPT Image Model ID. One BetterToken API Key works with all available models.

Verfügbare Optionen: gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst

Beispiel:"gpt-image-2"

promptstringerforderlich

A detailed description of the image to generate.

Beispiel:"A futuristic AI product poster on a light background, with glass textures, a clean composition, and a premium technology aesthetic."

ninteger | nullStandard: 1

Allowed range: 1–10; start with 1. Fewer images may be delivered than requested. Iterate data[] and use actual-delivery billing.

Erforderlicher Bereich: 1 <= x <= 10

Beispiel:1

sizestring | nullStandard: 1024x1024

Omit or use auto for automatic sizing. For WxH, both dimensions must be positive multiples of 16, each at most 3840, aspect ratio at most 3:1, total pixels 655360–8294400. Examples are not an exhaustive enum; 2080x2080 also meets the geometry rules. Inspect actual decoded dimensions. Valid parameters do not guarantee an available service.

Beispiel:"1024x1024"

Beispiel: ["auto","1024x1024","2048x2048","2080x2080","3840x2160"]

response_formatenum<string>Standard: b64_json

Use b64_json.

Verfügbare Optionen: b64_json

Beispiel:"b64_json"

output_formatstringStandard: png

Requested output format; png is recommended, but the response is not guaranteed to have been transcoded to PNG. Detect PNG, JPEG, or WebP from actual bytes before choosing an extension. Convert locally if a specific format is required.

Beispiel:"png"

qualityenum<string | null>Standard: auto

gpt-image-2 accepts auto, low, medium, high. The two 2.5 models also accept xhigh and max. Omit for the model default; JSON null is treated as omitted, while multipart requires a nonempty string. Valid values do not guarantee an available service for every model, size, and editing combination. Acceptance does not guarantee that a higher setting improves image quality.

Verfügbare Optionen: auto, low, medium, high, xhigh, max, null

Beispiel:"auto"

Antwort

200BetterToken billing extension. Settlement follows the actual delivered pixels and billing tier, which can differ from the requested tier. Amounts are decimal strings; use the returned values.

OpenAI-compatible image response. Iterate data[] and read each image from b64_json. Fewer images may be delivered than requested.

createdinteger

Beispiel:1710000000

dataobject[]

Show child attributes

data[].b64_jsonstring

Base64-encoded image content.

Beispiel:"iVBORw0KGgoAAAANSUhEUgAA...(truncated)"

data[].revised_promptstring

bettertoken_image_billingobject

BetterToken billing extension. Settlement follows the actual delivered pixels and billing tier, which can differ from the requested tier. Amounts are decimal strings; use the returned values.

Show child attributes

bettertoken_image_billing.currencystring

Settlement currency; do not assume a fixed currency.

bettertoken_image_billing.settled_amountstring

Final request amount as a decimal string; use decimal arithmetic for calculations.

bettertoken_image_billing.outputsobject[]

Delivered image indices, actual dimensions, billing tiers, and per-image amounts. index is zero-based and corresponds to data[].

bettertoken_image_billing.outputs[].indexinteger

Erforderlicher Bereich: x >= 0

bettertoken_image_billing.outputs[].widthinteger

Erforderlicher Bereich: x >= 1

bettertoken_image_billing.outputs[].heightinteger

Erforderlicher Bereich: x >= 1

bettertoken_image_billing.outputs[].billing_resolutionenum<string>

Verfügbare Optionen: 1K, 2K, 4K

bettertoken_image_billing.outputs[].currencystring

bettertoken_image_billing.outputs[].amountstring

Settled amount for this image as a decimal string.

bettertoken_image_billing.partialboolean

bettertoken_image_billing.requested_resolutionstring

Resolution tier inferred from the request; it may differ from the actual billing tier.

Beispiel

{
  "created": 1710000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...(truncated)",
      "revised_prompt": "<string>"
    }
  ],
  "bettertoken_image_billing": {
    "currency": "<string>",
    "settled_amount": "<string>",
    "outputs": [
      {
        "index": 0,
        "width": 1,
        "height": 1,
        "billing_resolution": "1K",
        "currency": "<string>",
        "amount": "<string>"
      }
    ],
    "partial": false,
    "requested_resolution": "<string>"
  }
}

400Invalid request format, missing parameters, malformed JSON or multipart data, or invalid dimensions.

errorobject

Show child attributes

error.messagestring

Beispiel:"invalid request"

error.typestring

Beispiel:"invalid_request_error"

error.codestring

Beispiel:"invalid_request"

messagestring

Beispiel:"insufficient quota"

Beispiel

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

401The BetterToken API Key is missing or invalid.

errorobject

Show child attributes

error.messagestring

Beispiel:"invalid request"

error.typestring

Beispiel:"invalid_request_error"

error.codestring

Beispiel:"invalid_request"

messagestring

Beispiel:"insufficient quota"

Beispiel

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

402The account has insufficient credit or balance.

errorobject

Show child attributes

error.messagestring

Beispiel:"invalid request"

error.typestring

Beispiel:"invalid_request_error"

error.codestring

Beispiel:"invalid_request"

messagestring

Beispiel:"insufficient quota"

Beispiel

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

403Insufficient balance or token quota: error.code is insufficient_user_quota. Funds must also cover the reservation of the highest-tier unit price times the image-count upper bound, before actual-delivery settlement. Inspect error.code rather than treating every 403 as an authorization error.

errorobject

Show child attributes

error.codestring

error.messagestring

error.typestring

Beispiel

{
  "error": {
    "code": "insufficient_user_quota",
    "message": "Insufficient balance or token quota."
  }
}

429A rate or concurrency limit was reached, or the upstream service is busy.

errorobject

Show child attributes

error.messagestring

Beispiel:"invalid request"

error.typestring

Beispiel:"invalid_request_error"

error.codestring

Beispiel:"invalid_request"

messagestring

Beispiel:"insufficient quota"

Beispiel

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}

500The gateway or upstream service returned an error.

errorobject

Show child attributes

error.messagestring

Beispiel:"invalid request"

error.typestring

Beispiel:"invalid_request_error"

error.codestring

Beispiel:"invalid_request"

messagestring

Beispiel:"insufficient quota"

Beispiel

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request"
  },
  "message": "insufficient quota"
}