HiAPI
Blog

Tutorial

So verwenden Sie qwen-image-2.0-pro über die HiAPI API: curl, Python und eine funktionierende Anfrage

Eine praktische Integrationsübung für Entwickler: erster erfolgreicher Aufruf, Aufbau der Anfrage und Fehlersuche

Nov 17, 2026
Minimalistisches Cover-Bild aus überlagerten Papierschichten: Auf cremefarbenem Grund staffeln sich mehrere grafitfarbene dünne Papierbögen in geringer Schärfentiefe nach hinten, in der Mitte als Akzent ein Blatt in Terrakotta.
Auf dieser Seite

Was qwen-image-2.0-pro API-Nutzern bietet

qwen-image-2.0-pro ist ein Bildgenerierungsmodell, das über HTTP aufgerufen wird. Aus der Perspektive Ihres Codes verhält es sich wie ein Chat-Completion-Endpunkt: Sie senden eine JSON-Nutzlast, die das gewünschte Bild beschreibt, und erhalten eine JSON-Antwort mit dem generierten Bild.

Der Vorteil des Zugriffs über die HiAPI API liegt in der Konsistenz. Ein API-Schlüssel, eine Basis-URL und eine Anfragestruktur funktionieren modellübergreifend. Wenn Sie später den Modellbezeichner ändern oder Parameter anpassen, bleibt der umgebende Code unverändert. Sie müssen weder für jedes Bildmodell, das Sie ausprobieren, ein neues SDK lernen noch mehrere Zugangsdaten verwalten.

Dieses Tutorial führt zunächst mit curl einen vollständigen ersten Aufruf durch, überträgt ihn dann auf Python, erklärt, wie man das Bild aus der Antwort ausliest, und endet mit einer Fehlersuchliste und einem kleinen wiederverwendbaren Wrapper. Alle Beispiele verwenden dieselbe Nutzlast und dieselbe Umgebungsvariable für den Schlüssel, sodass das, was im Terminal funktioniert, ohne Änderungen in einem Skript läuft.

Voraussetzungen und Vorbereitung des Schlüssels

Bevor Sie Code schreiben, stellen Sie sicher, dass die folgenden drei Dinge bereit sind.

1. HiAPI-Konto und API-Schlüssel

Erstellen Sie ein Konto und generieren Sie einen API-Schlüssel im Dashboard. Der Schlüssel ist vertraulich und sollte wie ein Passwort behandelt werden. Fügen Sie ihn nicht in Quelldateien ein, die in die Versionskontrolle eingecheckt werden.

2. Schlüssel als Umgebungsvariable exportieren

Die folgenden Beispiele lesen den Schlüssel aus HIAPI_API_KEY, sodass dieselben Befehle und Skripte lokal und in CI ohne Änderungen laufen.

export HIAPI_API_KEY="your_key_here"

Verwenden Sie in Windows PowerShell $env:HIAPI_API_KEY = "your_key_here". Legen Sie ihn in CI als geheime Umgebungsvariable in der Pipeline-Konfiguration fest.

3. Werkzeug zum Senden von HTTP-Anfragen

curl ist in der Regel vorinstalliert. Für Python benötigen Sie Python 3 und die Bibliothek requests:

pip install requests

Bevor Sie fortfahren, können Sie prüfen, ob der Schlüssel in Ihrer Shell sichtbar ist:

# macOS / Linux
echo "${HIAPI_API_KEY:0:4}..."

Wenn keine Ausgabe erfolgt, ist die Variable nicht gesetzt, und alle Anfragen schlagen mit einem Authentifizierungsfehler fehl. Beheben Sie dieses Problem zuerst.

Minimale funktionsfähige Anfrage mit curl

Der schnellste Weg, die Konnektivität zu prüfen, ist ein curl-Aufruf, der den Schlüssel aus der Umgebungsvariable liest. Die Nutzlast ist ein JSON-Objekt mit einem model-Feld und einem messages-Array im Stil von Chat-Completion.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0-pro",
    "messages": [
      {
        "role": "user",
        "content": "A small ceramic mug on a wooden table, soft morning light, product photo"
      }
    ]
  }'

Drei Details sind hier wichtig. Der Authorization-Header verwendet das Bearer-Schema. Der model-Wert muss genau mit dem Modellbezeichner übereinstimmen. content ist ein reiner String-Prompt, der das Bild beschreibt.

Bei erfolgreicher Anfrage sehen Sie die JSON-Antwort im Terminal. Bei einem Fehler sehen Sie den HTTP-Statuscode und die Fehlermeldung. Prüfen Sie den Statuscode, bevor Sie den Antworttext lesen: 401 bedeutet falscher oder fehlender Schlüssel, 400 deutet meist auf eine fehlerhafte Nutzlast hin, und 404 oder ein Modell-nicht-gefunden-Fehler bedeutet, dass der Modellbezeichner falsch ist.

Sobald dieser Befehl eine erfolgreiche Antwort zurückgibt, ist die Konnektivität bestätigt, und Sie können mit dem Schreiben von Code fortfahren.

Dieselbe Anfrage in Python

Beim Übertragen des Aufrufs nach Python bleibt die Nutzlast identisch. Der einzige Unterschied liegt darin, wie die Umgebungsvariable gelesen und die Anfrage serialisiert wird.

import json
import os

import requests

api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "qwen-image-2.0-pro",
    "messages": [
        {
            "role": "user",
            "content": "A small ceramic mug on a wooden table, soft morning light, product photo",
        }
    ],
}

response = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))

Beachten Sie, dass json=payload requests den Content-Type-Header automatisch setzen und den Anfragetext serialisieren lässt. timeout ist wichtig, weil die Bildgenerierung länger dauern kann als eine typische Text-Completion; 120 Sekunden sind ein vernünftiger Ausgangswert. raise_for_status() wandelt Fehlerstatuscodes in Ausnahmen um, sodass Fehler nicht unbemerkt bleiben.

Wenn Sie dieses Skript ausführen, sollten Sie dasselbe JSON erhalten wie mit curl. Ist das nicht der Fall, unterscheidet sich Ihre Umgebung von der Shell, in der curl erfolgreich lief – am häufigsten die Schlüsselvariable.

Antwort lesen und Bildausgabe verarbeiten

Die Antwort folgt der Chat-Completion-Struktur, sodass das generierte Bild über denselben Pfad abgerufen wird, den Sie für Textantworten verwenden. Prüfen Sie zunächst das ausgegebene JSON; die Struktur wird Ihnen vertraut vorkommen:

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

Das generierte Bild erscheint im Inhalt der Assistenten-Nachricht, typischerweise als URL oder base64-kodierte Nutzlast, je nachdem, wie das Modell Medien zurückgibt. Gehen Sie nicht von einem der beiden Formate aus; lesen Sie den Wert und verzweigen Sie anhand seines Präfixes:

content = data["choices"][0]["message"]["content"]

if isinstance(content, str) and content.startswith("http"):
    image_url = content
    # Download and save if you want a local copy
    image_bytes = requests.get(image_url, timeout=60).content
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from URL")
else:
    # Treat as base64-encoded image data
    import base64

    image_bytes = base64.b64decode(content)
    with open("output.png", "wb") as f:
        f.write(image_bytes)
    print("saved output.png from base64")

Zwei praktische Hinweise. Wenn der Inhalt eine URL ist, behandeln Sie sie als temporären Link und laden Sie sie so schnell wie möglich herunter, anstatt sie im Produkt direkt zu verlinken. Wenn es base64 ist, kapseln Sie den Dekodierungsvorgang, damit fehlerhafte Nutzlasten einen abfangbaren Fehler auslösen. Schreiben Sie die Rohantwort immer vor dem Parsen in eine Protokolldatei, damit Sie debuggen können, ohne die möglicherweise langsame Anfrage erneut auszuführen.

Fehlersuchliste für fehlgeschlagene Anfragen

Wenn eine Anfrage fehlschlägt, überschreiben Sie nicht voreilig den gesamten Aufruf. Führen Sie die folgenden Prüfungen der Reihe nach aus und stoppen Sie beim ersten Fehler. Jede Prüfung isoliert eine Variable.

1. Authentifizierung

Prüfen Sie zuerst den Statuscode. 401 bedeutet, dass der Schlüssel fehlt, abgelaufen oder falsch formatiert ist. Vergewissern Sie sich, dass die Umgebungsvariable in der aktuellen Shell gesetzt ist, dass Sie das Bearer-Präfix verwendet haben und dass im Header keine Leerzeichen am Ende stehen.

2. Modellbezeichner

Ein Modell-nicht-gefunden-Fehler bedeutet, dass der model-Wert nicht exakt mit dem verfügbaren Modell übereinstimmt. Groß-/Kleinschreibung und Suffixe sind entscheidend. Vergleichen Sie Ihren Wert Zeichen für Zeichen mit der Dokumentationsseite des Modells.

3. Nutzlaststruktur

400 stammt meist von einem fehlerhaften Anfragetext. Vergewissern Sie sich, dass messages ein Array ist, jede Nachricht role und content enthält und das JSON gültig ist. Wenn Sie die Nutzlast vor dem Senden durch jq oder python -m json.tool schicken, können Sie Syntaxfehler abfangen.

4. Antwortverarbeitung

Wenn die Anfrage erfolgreich ist, das Skript aber abstürzt, liegt das Problem im Parsing-Code, nicht an der API. Protokollieren Sie den Rohantworttext vor dem Aufteilen und vergewissern Sie sich, dass der von Ihnen gelesene Pfad tatsächlich existiert. Das Bild kann in einem Aufruf als URL und in einem anderen als base64 zurückkommen; verzweigen Sie daher anhand des Inhalts, statt Annahmen zu treffen.

5. Timeouts und Wiederholungen

Die Bildgenerierung kann langsam sein. Bei einem Timeout erhöhen Sie das Client-Timeout und wiederholen Sie den Aufruf einmal. Vermeiden Sie Wiederholungen bei 4xx-Fehlern, da sie auf dieselbe Weise erneut fehlschlagen würden.

Eine nützliche Gewohnheit: Bewahren Sie eine Kopie einer bekanntermaßen funktionierenden Anfrage auf und vergleichen Sie fehlgeschlagene Anfragen damit. Bei den meisten Fehlern fehlt nur ein einziges Feld.

Als wiederverwendbaren Client kapseln

Sobald der Aufruf funktioniert, kapseln Sie ihn hinter einer kleinen Funktion, damit Modell- und Parameteränderungen an einer Stelle konzentriert sind. Dieser Wrapper verwaltet die Schlüsselsuche, Header und Fehlerbehandlung zentral:

import base64
import os

import requests

HIAPI_BASE = "https://api.hiapi.ai/v1"
DEFAULT_MODEL = "qwen-image-2.0-pro"


def generate_image(prompt: str, model: str = DEFAULT_MODEL) -> bytes:
    """Generate an image and return its raw bytes."""
    api_key = os.environ["HIAPI_API_KEY"]
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
    }
    response = requests.post(
        f"{HIAPI_BASE}/chat/completions",
        headers={"Authorization": f"Bearer {api_key}"},
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    content = response.json()["choices"][0]["message"]["content"]

    if isinstance(content, str) and content.startswith("http"):
        return requests.get(content, timeout=60).content
    return base64.b64decode(content)

Der Aufrufcode wird zu einer Zeile: open("out.png", "wb").write(generate_image("A ceramic mug on a wooden table")). Wenn Sie später zu einem anderen Bildmodell wechseln oder Parameter hinzufügen, müssen Sie nur diese Funktion ändern. Der Modellbezeichner und alle Parameterdetails stehen auf der Modellseite; Sie können sich zuerst die Details des Modells qwen-image-2.0-pro ansehen und es dann anbinden.

Beginnen Sie mit dem curl-Aufruf, dann mit dem Python-Skript und schließlich mit der Kapselung. Jeder Schritt bestätigt einen kleineren Teil, bevor Sie die nächste Ebene aufbauen.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen