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
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 →-
Tutorial
kling-image-4.0 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzgebiete und Integrationspunkte
-
Tutorial
So rufen Sie gemini-omni-1.1-flash über die HiAPI-API auf: curl- und Python-Leitfaden
-
Tutorial
So rufen Sie die veo-3.1 Text-zu-Video-API auf: curl- und Python-Beispiele
Ein praxisorientierter Integrationsleitfaden für Entwickler