Wie verwendet man die Grok Image 2.0 Image-to-Image API? Ein Referenzbild, ein Satz, ein bearbeitetes Bild

Wie verwendet man die Grok Image 2.0 Image-to-Image API? Man übergibt eine öffentlich erreichbare Referenzbild-URL plus eine Bearbeitungsanweisung, reicht sie per POST /v1/tasks ein und erhält durch Polling data.output[0].url – das ist das bearbeitete Bild. Jedes Bild kostet fest $0.065, 1K und 2K zum gleichen Preis, keine Maske, keine Ebenen.

Grok Image 2.0 ist bereits auf HiAPI verfügbar: Modellseite Image-to-Image öffnen, ein Bild hochladen und bearbeiten. Neue Nutzer erhalten bei der Registrierung 200 Credits – genug für 1 Image-to-Image-Generierung (130 Credits).

TL;DR

• Was ist das: grok-imagine-image-2.0/image-to-image, von xAI; bearbeitet ein einzelnes Referenzbild per natürlichsprachlicher Anweisung – Hintergrund wechseln, kleine Objekte hinzufügen, Materialfarbe ändern, alles möglich.
• Was kostet es: $0.065 pro Bild, 1K / 2K sowie low / medium zum gleichen Preis; Abrechnung nur bei erfolgreicher Generierung, bei Fehlschlag automatische Rückerstattung. Für $10 etwa 153 Bilder.
• Schnellster Aufruf: Pflichtfelder sind nur prompt und image; image ist ein URL-String, kein Array.

Welche Parameter hat Grok Image 2.0 Image-to-Image?

Feld	Pflicht	Werte	Beschreibung
prompt	Ja	String	Bearbeitungsanweisung
image	Ja	String	Eine öffentlich erreichbare JPG / JPEG / PNG / WebP URL, kein Array
resolution	Nein	1k, 2k	Standard 1k
quality	Nein	low, medium	Standard medium; medium liefert mehr Details, low ist schneller
aspect_ratio	Nein	Dieselben 14 Werte wie bei Text-to-Image	Kann übergeben werden, hat aber keine Wirkung; das Ausgabeformat folgt dem Referenzbild

Pro Aufruf kann nur ein Referenzbild bearbeitet werden, ein Task liefert ein Bild; für mehrere Bilder reicht man mehrere Tasks parallel ein. Anfragen mit Feldnamen oder Werten außerhalb der obigen Tabelle geben 400 zurück.

Zwei Wege: Online-Test und API

Online-Test (1 Minute)

1. Modellseite Image-to-Image öffnen, anmelden und Referenzbild hochladen.
2. Bearbeitungsanweisung eingeben und Auflösung wählen.
3. Auf „Ausführen“ klicken und nach Erfolg Referenzbild und Ergebnis vergleichen.

API-Anbindung (5 Minuten)

1. Im Dashboard einen API Key erstellen.
2. Das Referenzbild unter einer öffentlich erreichbaren Adresse ablegen (eigenes CDN oder Objektspeicher).
3. Task per POST /v1/tasks einreichen, dann pollen oder Callback einrichten.
4. Nach Erfolg sofort data.output[0].url herunterladen.

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

Probiere direkt einen Bearbeitungs-Prompt aus: den alten Geigenbauer aus der Werkstatt mit Holzspänen auf einen sonnigen Markt versetzen, die Person bleibt unverändert. Mit diesem Prompt generieren → (der Link füllt nur den Prompt vor; das Referenzbild lädst du auf der Modellseite selbst hoch, Auflösung 2K wählen)

Referenzbild	Ergebnis

curl und Python: die erste Bildbearbeitung zum Laufen bringen

Zuerst den API Key setzen:

export HIAPI_API_KEY="sk-..."

Alle Anfragen enthalten Authorization: Bearer sk-<key>. Die Bildbearbeitung ist asynchron und nutzt dieselbe Task-Schnittstelle wie andere HiAPI-Modelle. Das Referenzbild wird serverseitig abgerufen; lokale Dateipfade funktionieren nicht, es muss eine öffentlich erreichbare URL sein.

Schritt 1, Task erstellen:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

Gibt sofort eine taskId zurück:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q" }
}

Schritt 2, bis zum Endzustand pollen:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q \
  -H "Authorization: Bearer $HIAPI_API_KEY"

data.status prüfen: success bedeutet Erfolg, fail bedeutet Fehlschlag; bei anderen Status weiter warten. Beispiel einer Erfolgsantwort:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

storage: "temp" und expireAt beachten: Die Ergebnis-URL ist temporär; nach Abschluss des Tasks sofort herunterladen oder in den eigenen Objektspeicher übertragen. Das Ausgabeformat folgt dem Referenzbild; im Beispiel ist das wirkungslose aspect_ratio weggelassen.

Python-Version:

Zuerst requests installieren (python3 -m pip install requests) und das obige HIAPI_API_KEY setzen. Das Skript pollt maximal 10 Minuten; nach Timeout die taskId behalten und weiter abfragen.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

Worauf vor dem Produktivbetrieb achten?

• Referenzbild zuerst öffentlich bereitstellen. Liegt das vom Nutzer hochgeladene Bild in einem privaten Bucket oder auf localhost, kann die Plattform es nicht abrufen und der Task schlägt asynchron fehl; vor dem Einreichen prüfen, ob der Link öffentlich erreichbar ist, und eine langfristig gültige Adresse verwenden (keine ablaufenden signierten Links).

• Anweisung als „was bleibt, was ändert sich“ formulieren. Zuerst den unveränderlichen Teil, dann den zu ändernden Teil schreiben; je enger der Änderungsumfang, desto stabiler. Weitere Formulierungen siehe Image-to-Image-Prompt-Vorlagen.

• Für Stapelverarbeitung Callback statt enger Polling-Schleife verwenden.

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" benachrichtigt beim Erreichen des Erfolgs- oder Fehler-Endzustands; der Empfänger dedupliziert nach taskId.

• Ergebnis sofort übertragen. data.output[0].url ist eine temporäre Adresse und läuft gemäß expireAt ab.

• Einen Task nur einmal einreichen. Nach der Antwort die Zuordnung von taskId zum Geschäftsvorgang speichern; doppeltes Einreichen kann mehrere Tasks erzeugen und jeweils kosten. Bei Timeout der Erstellanfrage ohne ID zuerst die Task-Aufzeichnungen prüfen, dann entscheiden, ob neu eingereicht wird.

• resolution explizit angeben. Standard ist 1k; 1K und 2K kosten gleich viel ($0.065), für finale Bilder direkt "2k" übergeben.

• Fehlerbehandlung. Zuerst HTTP-Status und code, message in der Antwort prüfen, dann data lesen. Bei Parameter- oder Authentifizierungsfehlern korrigieren und erneut einreichen; bei Task-Status fail den Fehler protokollieren und das Polling beenden.

Weiterführende Lektüre

• Modellseite Grok Image 2.0 Text-to-Image: gleiche Reihe, erzeugt neue Bilder nur aus Text.
• Was kostet die Grok Image 2.0 API?
• Grok Image 2.0 Text-to-Image API anbinden
• Grok Image 2.0 Image-to-Image Prompt-Vorlagen
• Authentifizierung und Schnellstart

Häufige Fragen

image als URL oder als Array übergeben? Als einzelner URL-String. Ein Array führt zu einem Typfehler. Für die Fusion mehrerer Bilder bitte ein Modell verwenden, das mehrere Referenzbilder unterstützt.

Was tun bei „additional properties not allowed“? input akzeptiert nur prompt, image, aspect_ratio, resolution, quality. Bei anderen Bearbeitungsmodellen übliche Felder wie image_urls, strength, mask, seed, negative_prompt sind hier nicht verfügbar; einfach entfernen.

Der Browser kann das Referenzbild öffnen – warum kann der Task trotzdem fehlschlagen? Die Plattform ruft das Bild serverseitig ab; das Referenzbild sollte ohne Anmeldung und aus dem öffentlichen Internet erreichbar sein; signierte Links müssen bis zum Abschluss des Abrufs gültig bleiben. Zugriffsrechte, Format und Gültigkeitsdauer des Links vor dem Einreichen prüfen.

Kann man mehrere Bilder auf einmal bearbeiten? Nein, ein Bild rein, ein Bild raus. Für Stapelverarbeitung mehrere Tasks parallel einreichen.

Warum ist Image-to-Image teurer als Text-to-Image? Image-to-Image kostet $0.065, Text-to-Image $0.052, also 25% mehr – für die Fähigkeit, „mit einem Referenzbild zu bearbeiten“.

Wie lange ist die Ausgabe-URL gültig? Temporärer Speicher; expireAt in der Antwort ist ein Unix-Zeitstempel. Nach erfolgreichem Task sofort herunterladen oder übertragen.

Muss man synchron auf das Ergebnis warten? Nein. Die Erstell-Schnittstelle kehrt sofort zurück, nachdem der Task eingereiht wurde; kurze Skripte pollen GET /v1/tasks/<taskId>, in der Produktion callback einrichten.

Jetzt das erste Bild bearbeiten

Zuerst HIAPI_API_KEY setzen, dann in den curl- und Python-Beispielen die image-Adresse durch die eigene öffentliche Bild-URL ersetzen. Um das Ergebnis vorab zu sehen, die Modellseite Image-to-Image öffnen, Bild hochladen und den obigen Prompt einfügen.