So verwenden Sie gpt-image-2-beta über die hiapi API: Parameter, Code und lauffähige Beispiele

gpt-image-2-beta ist der minimalistische Weg mit Festpreis zu GPT Image 2 auf hiapi: zwei Eingabefelder, ein Preis, keine Einstellungen für Seitenverhältnis oder Qualität. Dieser Leitfaden zeigt ein minimal lauffähiges Beispiel, die exakte Parameterstruktur (bestätigt durch Abfrage des Live-Endpunkts) und wie er im Vergleich zur Standardroute gpt-image-2/text-to-image abschneidet, damit Sie entscheiden können, wann welche Route die richtige ist.

Voraussetzungen

Sie benötigen einen API-Schlüssel von der API-Keys-Seite im hiapi-Dashboard – Schlüssel beginnen mit sk-. Den aktuellen Preis pro Bild finden Sie auf der Modellseite von gpt-image-2-beta und auf der Preisseite.

Wie jedes Bildmodell auf hiapi läuft dieses Modell auf dem einheitlichen asynchronen Task-Endpunkt:

• POST https://api.hiapi.ai/v1/tasks – erstellt einen Generierungs-Task
• GET https://api.hiapi.ai/v1/tasks/{taskId} – fragt den Task-Status ab

Was an der Beta-Route anders ist

gpt-image-2/text-to-image (die Standardroute) akzeptiert aspect_ratio + resolution und wird nach Auflösungsstufe abgerechnet ($0.03 für 1K, bis zu $0.06 für 4K). gpt-image-2-beta reduziert all das auf einen einheitlichen Festpreis von $0.02 pro Bild und ein optionales Feld size – ein wörtlicher Pixelmaß-String wie "1024x1024" oder "1600x900", kein Verhältnis. Wenn size vollständig weggelassen wird, fällt das Modell auf seine eigene Standard-Ausgabegröße zurück.

Der Preis dafür: Sie geben die feinkörnige Kontrolle über Verhältnis und Auflösung auf und erhalten dafür einen niedrigeren, einfacheren Preis. Er passt gut, wenn Sie einfach nur „günstig ein Bild generieren“ möchten und sich nicht um die exakte Komposition kümmern.

Minimal lauffähiges Beispiel (curl)

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

Das fertige Bild befindet sich unter data.output[0].url. Diese URL hat eine kurze expireAt-Gültigkeit – laden Sie sie sofort herunter und hosten Sie sie in Ihrem eigenen Speicher neu; verlinken Sie sie nicht direkt in Produktionsinhalten.

Beispielbild, erzeugt mit dem obigen curl-Aufruf (mit einem anderen Prompt), unter Verwendung von size: "1024x1024".

Python: Erstellen + Abfragen + auf Datenträger speichern

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

Parameterreferenz

Das input-Objekt von gpt-image-2-beta akzeptiert nur zwei Felder – die Struktur ist additionalProperties: false, daher wird alles andere direkt abgelehnt, statt stillschweigend ignoriert zu werden.

Feld	Typ	Erforderlich	Beschreibung
prompt	string	Ja	Die Textbeschreibung des zu generierenden Bildes.
size	string	Nein	Wörtliche Pixelmaße, z. B. "1024x1024", "1600x900". Kein Seitenverhältnis-Schlüsselwort. Wenn weggelassen, wird die Standard-Ausgabegröße des Modells verwendet.

Nicht unterstützte Angaben (und die Fehlermeldung, die Sie erhalten)

Die Beta-Struktur akzeptiert keines der Felder, die von der Standardroute gpt-image-2/text-to-image oder der OpenAI Images API verwendet werden – aspect_ratio, resolution, quality, background, moderation, output_format, output_compression, n, user oder style. Das Senden eines dieser Felder führt sofort zu HTTP 400, zum Beispiel:

{
  "code": 400,
  "data": null,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'quality', 'aspect_ratio' not allowed"
}

Wenn Sie Code von der Standardroute oder der OpenAI Images API migrieren, reduzieren Sie ihn zuerst auf prompt + size und richten Sie ihn dann auf gpt-image-2-beta.

Preise: Beta vs. Standard vs. @ext

Route	Preis	Steuerungsoptionen
gpt-image-2-beta	$0.02/Bild fest	Nur size (Pixelmaße)
gpt-image-2/text-to-image (Standard)	$0.03 (1K) / $0.04 (2K) / $0.06 (4K)	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	$0.007–$0.76, je nach Qualität × Auflösung	16 Seitenverhältnisse, Qualitätsstufen

Bevor Sie eine Route in der Produktion festlegen, prüfen Sie die Preisseite – die Preise eines bestimmten Modells können sich ändern.

Tipps für die Arbeit mit der Beta-Route

• Betrachten Sie die oben genannte Feldliste als aktuelle Vereinbarung, nicht als dauerhafte. Die Struktur oder Preisgestaltung der Beta-Route wird wahrscheinlicher angepasst als die der Standardroute – wenn Sie sich in der Produktion darauf verlassen, sehen Sie regelmäßig auf der Modellseite nach.
• Da size optional ist, übergeben Sie es immer explizit, wenn Ihr Layout auf eine bestimmte Größe angewiesen ist – verlassen Sie sich nicht darauf, dass der aktuelle Standardwert unverändert bleibt.
• Behandeln Sie status: "fail" wie bei jedem anderen hiapi-Bildmodell: Lesen Sie task.error.code / task.error.message und versuchen Sie es mit Backoff erneut, statt anzunehmen, dass jeder Fehlschlag vorübergehend ist.

Häufige Fragen

Ist gpt-image-2-beta dasselbe Modell wie gpt-image-2/text-to-image? Zugrunde liegt dasselbe GPT Image 2-Modell, aber die API-Route ist anders – die Beta-Route tauscht Parameterkontrolle gegen einen festen, niedrigeren Preis.

Kann ich ein bestimmtes Seitenverhältnis anfordern? Nicht direkt. Wählen Sie einen size-String mit dem gewünschten Breite:Höhe-Verhältnis (z. B. "1600x900" für 16:9), statt die aspect_ratio-Enumeration zu verwenden.

Was passiert, wenn ich size vollständig weglasse? Der Task ist trotzdem erfolgreich – das Modell verwendet seine eigene Standard-Ausgabegröße.

Weiterführende Lektüre

Für die voll funktionsfähige Route mit expliziter Kontrolle über Seitenverhältnis und Auflösung siehe So verwenden Sie gpt-image-2/text-to-image über die hiapi API. Bereit, es selbst auszuprobieren? Holen Sie sich einen Schlüssel von der API-Keys-Seite und führen Sie das obige curl-Beispiel aus.