Tutorial
Wie man minimax-h3-image Bild-zu-Bild auf hiapi mit curl und Python aufruft
Auf dieser Seite
Was der Bild-zu-Bild-Endpunkt erwartet
Bevor Sie Code schreiben, ist es hilfreich, den Aufbau eines Bild-zu-Bild-Aufrufs zu verstehen. Der minimax-h3-image-Bild-zu-Bild-Endpunkt nimmt Ihr Referenzbild (eines oder mehrere) sowie eine Textaufforderung entgegen und liefert ein neu generiertes Ergebnis zurück, das der Aufforderung folgt und zugleich am Referenzbild verankert ist.
Konzeptionell enthält jeder Request drei Teile:
- Modell-Routing – Sie adressieren
minimax-h3-imageüber die Aufgabeimage-to-image, alles über einen einzigen hiapi-Endpunkt. Sie brauchen keine separaten Zugangsdaten oder Hosts für die einzelnen Fähigkeiten. - Eingabe – ein Aufforderungs-String, ein oder mehrere Referenzbilder (URL- oder Base64-Last) sowie Generierungssteuerungen wie die Auflösungsstufe.
- Ausgabevertrag – der Aufruf ist asynchron. Sie erhalten eine Aufgabenkennung, fragen dann den Status ab und holen die generierte Bild-URL ab, wenn die Aufgabe abgeschlossen ist.
Der letzte Punkt ist wichtig. Bild-zu-Bild ist kein blockierender Aufruf, der Ihnen Pixel in derselben Antwort zurückgibt. Betrachten Sie den Absendeaufruf als „den Auftrag in die Warteschlange stellen“ und gestalten Sie Ihren Client von Anfang an rund um den Aufgabenlebenszyklus. Wenn Sie zuerst mit synchronem Verhalten entwerfen, müssen Sie die Integrationslogik später neu schreiben.
Da alles über dieselbe hiapi-Schnittstelle läuft, bleiben Request-Header, Authentifizierung und Antwort-Wrapper zwischen Modellen und Aufgaben konsistent. Lernen Sie es einmal für minimax-h3-image, und dasselbe Muster gilt überall auf der Plattform.
Ein minimaler lauffähiger Request
Beginnen Sie mit dem kleinsten Request, der beweist, dass Ihre Zugangsdaten, der Endpunkt und die Struktur Ihrer Nutzlast korrekt sind. Überstürzen Sie es nicht mit allen optionalen Feldern von Anfang an.
Der minimale Request-Body enthält:
- den Modellnamen
minimax-h3-image - den Aufgabentyp
image-to-image - einen
prompt, der beschreibt, welche Transformation Sie wünschen - ein einzelnes Referenzbildfeld
- eine Auflösungsstufe
Konzeptionell sieht die Nutzlast etwa so aus:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Verwandle diese Skizze in ein sauberes Produkt-Rendering auf weißem Hintergrund",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
Senden Sie ihn, bestätigen Sie, dass eine Aufgaben-ID zurückgegeben wird, und fragen Sie dann ein- oder zweimal manuell den Status ab, um die Zustandsübergänge zu beobachten. Wenn Sie eine Aufgaben-ID erhalten, sind Konnektivität und Authentifizierung in Ordnung, und Sie können mit dem eigentlichen Client fortfahren. Wenn nicht, halten Sie an und lesen Sie den Fehler-Response-Body – er zeigt in der Regel direkt auf das problematische Feld.
Speichern Sie diesen Request als Smoke-Test. Wenn spätere Änderungen Ihre Pipeline beschädigen, zeigt ein erneuter Lauf dieses minimalen Requests sofort, ob das Problem in Ihrer Nutzlast oder im umgebenden Code liegt.
Aufruf mit curl
curl ist der schnellste Weg, um rohe Requests und Antworten zu sehen. Schreiben Sie den JSON-Request-Body in eine Datei, damit Sie beim Bearbeiten nicht mit Shell-Anführungszeichen kämpfen müssen.
cat > payload.json <<'JSON'
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Verwandle dieses Foto in einen Aquarell-Illustrationsstil",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
JSON
curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
--data @payload.json
Zwei Header tragen die Hauptlast: Authorization mit dem Bearer-Token und Content-Type: application/json. Halten Sie beide von der Versionskontrolle fern – lesen Sie den Schlüssel aus einer Umgebungsvariable, statt ihn in den Befehl einzufügen.
Bei erfolgreicher Übermittlung erfassen Sie die zurückgegebene Aufgaben-ID und fragen sie ab:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Die Antwort enthält ein Statusfeld und nach Abschluss auch ein Ergebnis. Extrahieren Sie mit jq nur die Felder, die Sie interessieren:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'
Das ist auch der einfachste Weg, die Nutzlast zu debuggen: curl zeigt genau, was Sie gesendet haben und was zurückkam, ohne dass eine Client-Bibliothek etwas verbirgt.
Aufruf mit Python
Die Python-Version sollte den curl-Ablauf widerspiegeln: übermitteln, ID erfassen, bis zum Endzustand abfragen, Ergebnis abrufen. Verwenden Sie requests mit einer Session, damit Verbindungswiederverwendung und Standard-Header nur einmal behandelt werden müssen.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
def submit(prompt: str, image: str, resolution: str = "1024") -> str:
body = {
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": prompt,
"image": image,
"resolution": resolution,
},
}
resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()["id"]
def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"Aufgabe {task_id} wurde nicht innerhalb von {timeout} Sekunden abgeschlossen")
if __name__ == "__main__":
task_id = submit(
"Verwandle dieses Bild in ein flaches Vektorposter",
"https://example.com/reference.png",
)
print("Übermittelt:", task_id)
result = poll(task_id)
print(result)
Wesentliche Details: raise_for_status() macht HTTP-Fehler zu Ausnahmen statt zu stillem Scheitern; die Polling-Schleife hat sowohl eine Frist als auch ein Intervall; Endzustände werden explizit geprüft. Extrahieren Sie die Bild-URL aus dem Ergebnisobjekt erst, nachdem der Status einen Endzustand erreicht hat, niemals vorher.
Mehrere Referenzbilder verwenden
Ein einzelnes Referenzbild reicht oft nicht aus. Vielleicht möchten Sie das Gesicht aus einem Foto behalten und gleichzeitig die Komposition eines anderen übernehmen oder eine Textur und einen Umriss verschmelzen. Minimax-h3-image Bild-zu-Bild unterstützt mehrere Referenzeingaben über das Pluralfeld image.
Strukturell kann das input-Objekt ein einzelnes Referenzbild im Feld image tragen; wenn Sie mehrere haben, verwenden Sie das Array images:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "Behalte die Person aus dem ersten Bild und verwende den Hintergrundstil des zweiten Bildes",
"images": [
"https://example.com/person.png",
"https://example.com/background.png"
],
"resolution": "1024"
}
}
Die Reihenfolge ist bedeutsam. Referenzindex 0 ist Ihr Hauptobjekt, nachfolgende Einträge sind unterstützender Kontext, daher sollte die Formulierung der Aufforderung mit der Reihenfolge übereinstimmen, in der Sie senden. Wenn das Ergebnis ein Referenzbild ignoriert, liegt die Ursache meist in einer mehrdeutigen Aufforderung und nicht in einem defekten Feld – formulieren Sie in der Aufforderung ausdrücklich, welches Bild welche Eigenschaft bestimmt.
Praktische Regeln für die Arbeit mit mehreren Referenzen:
- Halten Sie die Anzahl schlank. Verwenden Sie nur die Referenzbilder, die die jeweilige Aufforderung wirklich benötigt; zusätzliche verwässern die Kontrolle.
- Gleichen Sie das Seitenverhältnis möglichst an, damit das Modell nicht widersprüchliche Kompositionen miteinander vereinbaren muss.
- Verwenden Sie in demselben Request konsistent öffentliche URLs oder Base64, mischen Sie die Übertragungsarten nicht.
Senden Sie während der Integration einmal einen Request mit zwei Bildern, prüfen Sie, ob beide Referenzbilder die Ausgabe erkennbar beeinflusst haben, und bauen Sie erst dann komplexere Logik darauf auf.
Auflösungsstufe wählen
Das Feld resolution wählt die Ausgabestufe für minimax-h3-image Bild-zu-Bild. Es ist nicht nur ein oberflächlicher Regler – es verändert den Rechenaufwand, die Antwortlatenz und die Nutzlastgröße, die Sie am Ende verarbeiten müssen.
So treffen Sie die Abwägung:
- Wählen Sie die kleinste Stufe, die den Zielkontext erfüllt. Miniaturansichten in einer Listenansicht brauchen nicht dieselbe Stufe wie ein Hero-Banner. Hochauflösende Ausgaben nachträglich herunterzuskalieren kostet sowohl Zeit als auch Geld.
- Rechnen Sie mit steigender Latenz bei höherer Auflösung. Höhere Stufen leisten mehr Arbeit pro Request, daher sollten Ihre Polling-Timeouts und Intervallbudgets die gewählte Stufe widerspiegeln.
- Achten Sie auf die Nutzlastgröße. Base64-Referenzeingaben und hochauflösende Ausgaben vergrößern beide das Übertragungsvolumen; wenn Sie viele Bilder bewegen, sollten Sie auf Request- und Response-Body achten.
Die Abrechnung folgt der von Ihnen angeforderten Auflösungsstufe – Requests werden nach der Stufe abgerechnet, mit der sie laufen, sodass ein zu große Stufe für kleine Anwendungsfälle unbemerkt mehr kostet. Prüfen Sie die aktuellen Tarife im Preisübersicht-Panel, statt Annahmen fest zu codieren.
Eine sinnvolle Integrationsstrategie: Verwenden Sie in der Entwicklungsphase eine mittlere Stufe für Geschwindigkeit und heben Sie zentrale Assets erst auf höhere Stufen, wenn Aufforderungen und Referenzbild-Set feststehen. Eine späte Änderung der Auflösung macht Ihre Latenzmessungen ungültig, daher sollten Sie auf der Stufe benchmarken, die Sie tatsächlich in Produktion einsetzen wollen.
Den asynchronen Lebenszyklus meistern
Jeder Bild-zu-Bild-Aufruf auf hiapi folgt derselben Schleife: übermitteln, Aufgaben-ID erfassen, bis zum Endzustand abfragen, dann das Ergebnis abrufen. Diese Schleife robust zu machen, ist der Großteil der Arbeit an einem produktionsreifen Client.
Übermitteln und protokollieren
Behandeln Sie die Aufgaben-ID als Ihr dauerhaftes Handle. Protokollieren Sie sie sofort, wenn die Absendeantwort eintrifft, bevor Sie irgendetwas anderes tun – wenn der Prozess mitten im Polling abstürzt, ermöglicht Ihnen diese ID die Wiederherstellung, statt neu zu generieren.
Mit Backoff abfragen
Festes Polling alle zwei Sekunden ist für interaktive Nutzung in Ordnung, aber für lange Batches verschwenderisch. Beginnen Sie mit einem kurzen Intervall und erhöhen Sie es schrittweise, mit einer Obergrenze für das maximale Intervall, sodass Sie den Abschluss dennoch zeitnah erkennen.
def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
return min(current * factor, cap)
Endzustände respektieren
Verlassen Sie die Schleife nur bei Erfolg oder Fehler. Jede nicht-leere Antwort als „fertig“ zu behandeln, ist der häufigste asynchrone Bug – Sie lesen dann ein Ergebnis, das noch nicht existiert.
Alles begrenzen
Setzen Sie für jeden HTTP-Aufruf ein Timeout und für die Aufgabe insgesamt eine Frist. Wenn die Frist überschritten wird, werfen Sie einen klaren Fehler, statt endlos zu drehen. Bei vorübergehenden Netzwerkfehlern wiederholen Sie das Polling mit Backoff; senden Sie nicht blind erneut ab, da dies doppelte Arbeit verursacht.
Aufräumen
Sobald Sie das Ergebnis abgerufen haben, persistieren Sie die Bild-URL oder die Bytes zeitnah in Ihrem eigenen Speicher. Aufgabenergebnisse sind temporäre Handles, nicht das langfristige CDN Ihrer Anwendung.
Fehlerbehebung und Produktions-Checkliste
Dies sind die Fehler, auf die Entwickler bei der Verwendung von minimax-h3-image Bild-zu-Bild zuerst stoßen, sowie Prüfpunkte, die sie verhindern.
Fehler beim ersten Lauf
- 401 / 403 – Bearer-Token fehlt, ist abgelaufen oder enthält führende/nachfolgende Leerzeichen. Stellen Sie sicher, dass die Umgebungsvariable in der Shell exportiert ist, die den Request ausführt.
- 422 oder Validierungsfehler – prüfen Sie den Fehler-Response-Body; er zeigt in der Regel das Feld an. Häufige Ursache ist ein
promptauf oberster Ebene statt innerhalb voninput. - Fehlerhaftes JSON – validieren Sie Ihre Nutzlastdatei mit
jq ., bevor Sie senden.
Laufzeitfehler
- Aufgabe wird nie abgeschlossen – stellen Sie sicher, dass Sie mit der tatsächlich erhaltenen ID abfragen und nicht mit einem Platzhalter. Prüfen Sie, ob Ihre Frist für die gewählte Auflösungsstufe lang genug ist.
- Ergebnis einer „abgeschlossenen“ Aufgabe ist leer – lesen Sie das Statusfeld genau; auch Fehlerzustände liefern einen Response-Body.
- Referenzbild wird ignoriert – prüfen Sie die Formulierung der Aufforderung und die Reihenfolge der Referenzbilder, bevor Sie das Modell verantwortlich machen.
Checkliste vor dem Deployment
- API-Schlüssel und Basis-URL werden aus Umgebungsvariablen gelesen und niemals ins Repository eingecheckt.
- Jeder HTTP-Aufruf hat ein explizites Timeout.
- Das Polling verwendet begrenztes Backoff mit einer harten Gesamtfrist.
- Endzustände werden explizit behandelt; es fällt nicht in den Ergebnisanalyse-Zweig.
- Ergebnisse werden von Ihrer Anwendung heruntergeladen und gespeichert, nicht aus der Aufgabenantwort hot-verlinkt.
- Aufforderungen mit mehreren Referenzen geben an, welches Bild welche Eigenschaft steuert.
- Die Auflösungsstufe wurde mit den Werten benchmarkt, die Sie in Produktion einsetzen wollen.
- Protokolle erfassen die Aufgaben-ID, damit fehlgeschlagene Jobs nachvollziehbar und wiederherstellbar sind.
Wenn etwas schiefgeht, führen Sie erneut den minimalen Request von oben aus – er isoliert, ob das Problem in Ihrer Nutzlast oder im umgebenden Code liegt. Mit der Request-Struktur, den curl- und Python-Clients, der Behandlung mehrerer Referenzen und einer disziplinierten Polling-Schleife haben Sie alles, was Sie brauchen, um minimax-h3-image Bild-zu-Bild auf hiapi zuverlässig in Produktion zu bringen.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen