Grok Imagine Image 2.0 API mit EvoLink nutzen

Was Sie bauen werden

Am Ende des Leitfadens kann Ihre Anwendung:

1. Erstellen Sie eine Text-zu-Bild-Aufgabe.
2. Wechseln Sie zur Referenzbearbeitung, ohne die Modell-IDs zu ändern;
3. Verwenden Sie indizierte Referenzen in einer Eingabeaufforderung mit mehreren Bildern.
4. Verfolgen Sie eine asynchrone Aufgabe anhand der ID.
5. einen Abschlussrückruf sicher annehmen;
6. Ergebnisse beibehalten, bevor ihre 24-Stunden-URLs ablaufen;
7. Endverbrauch und Rückerstattungen für fehlgeschlagene Aufgaben abgleichen;
8. Übergabe an eine Ausweichroute, wenn die Arbeitslast oder das Aufgabenergebnis dies erfordern.

Bevor Sie beginnen

Schritt 1: Bewahren Sie den API-Schlüssel serverseitig auf

Legen Sie für einen Shell-Test den Schlüssel in einer Umgebungsvariablen fest:

export EVOLINK_API_KEY="your_api_key"

Schritt 2: Erstellen Sie eine Text-zu-Bild-Aufgabe

curl --request POST "https://api.evolink.ai/v1/images/generations" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Editorial product photograph of a teal glass perfume bottle on pale limestone, warm coastal morning light, restrained luxury art direction, no text or logos",
    "size": "1:1",
    "resolution": "1K",
    "quality": "medium",
    "n": 1
  }'

{
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "grok-imagine-image-2.0",
  "object": "image.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "image",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 3.06,
    "user_group": "default"
  }
}

Der oben angegebene Reservierungswert ist ein Dokumentationsbeispiel, kein Preisversprechen und keine endgültige Gebühr. Nutzen Sie die aktuelle Modellseite für Live-Preise und die Terminal-Task-Antwort für die endgültige Nutzung.

Schritt 3: Fragen Sie die asynchrone Aufgabe ab

curl --request GET \
  "https://api.evolink.ai/v1/tasks/task-unified-1757156493-imcg5zqt" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}"

{
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "grok-imagine-image-2.0",
  "object": "image.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://cdn.evolink.ai/images/generated-image.jpg"],
  "result_data": [
    {
      "url": "https://cdn.evolink.ai/images/generated-image.jpg",
      "mime_type": "image/jpeg"
    }
  ],
  "type": "image",
  "usage": {
    "credits_used": 3.06,
    "cost": {
      "credits": 3.06,
      "cny": 0.31,
      "usd": 0.05
    }
  }
}

Diese numerischen Werte sind Beispielantwortwerte. Notieren Sie die von Ihrer eigenen Terminalaufgabe zurückgegebenen Werte. Verwenden Sie dieses Beispiel nicht zur Berechnung der Kundenabrechnung.

Schritt 4: Kontrolliertes Polling hinzufügen

Die Abfrage sollte bei einem Terminalstatus angehalten, zwischen Anfragen unterbrochen und ein Anwendungs-Timeout erzwungen werden. Das folgende serverseitige TypeScript-Beispiel hält den Aufgabenworkflow explizit:

type GrokTaskStatus = "processing" | "completed" | "failed";

type GrokTask = {
  id: string;
  status: GrokTaskStatus;
  progress: number;
  results?: string[];
  error?: {
    code: string;
    message: string;
    type: "task_error";
  };
};

const API_BASE_URL = "https://api.evolink.ai";

async function getTask(apiKey: string, taskId: string): Promise<GrokTask> {
  const response = await fetch(`${API_BASE_URL}/v1/tasks/${taskId}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
    cache: "no-store",
  });

  if (!response.ok) {
    throw new Error(`Task query failed with HTTP ${response.status}`);
  }

  return response.json() as Promise<GrokTask>;
}

async function waitForTask(
  apiKey: string,
  taskId: string,
  timeoutMs = 180_000,
): Promise<GrokTask> {
  const startedAt = Date.now();
  let intervalMs = 2_000;

  while (Date.now() - startedAt < timeoutMs) {
    const task = await getTask(apiKey, taskId);

    if (task.status === "completed" || task.status === "failed") {
      return task;
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
    intervalMs = Math.min(Math.round(intervalMs * 1.5), 10_000);
  }

  throw new Error("Grok Imagine Image 2.0 task timed out in the application");
}

Ein Anwendungs-Timeout ist kein Beweis dafür, dass die Upstream-Aufgabe fehlgeschlagen ist. Bevor Sie die Generierung erneut versuchen, fragen Sie die ursprüngliche Aufgabe erneut ab oder verwenden Sie eine Idempotenzstrategie in Ihrer eigenen Jobschicht. Andernfalls kann ein Client-Timeout zu doppelten abrechenbaren Aufgaben führen.

Schritt 5: Wechseln Sie zur Einzelreferenzbearbeitung

curl --request POST "https://api.evolink.ai/v1/images/generations" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Move the chair into a quiet rain-soaked garden room. Preserve the chair shape, teal upholstery, camera angle, and scale. Change only the environment and reflected light.",
    "image_urls": [
      "https://example.com/chair.webp"
    ],
    "size": "4:3",
    "resolution": "1K",
    "quality": "medium",
    "n": 1
  }'

Ihre Anwendung sollte Anzahl, Protokoll, Dateityp und Servererreichbarkeit überprüfen, bevor Sie eine kostenpflichtige Aufgabe erstellen. Auf eine URL, die in einem angemeldeten Browser funktioniert, kann der Generierungsdienst möglicherweise immer noch nicht zugreifen.

Schritt 6: Mit mehreren Referenzen verfassen

curl --request POST "https://api.evolink.ai/v1/images/generations" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Place the person from <IMAGE_0> in the architectural setting from <IMAGE_1>, carrying the blue sculptural bag from <IMAGE_2>. Preserve the outfit silhouette and match the late-afternoon direction of light.",
    "image_urls": [
      "https://example.com/person.webp",
      "https://example.com/location.webp",
      "https://example.com/bag.webp"
    ],
    "size": "3:4",
    "resolution": "2K",
    "quality": "medium",
    "n": 1
  }'

Speichern Sie die genaue Array-Reihenfolge mit der Eingabeaufforderung. Wenn eine Benutzeroberfläche es jemandem ermöglicht, Uploads neu anzuordnen, aktualisieren Sie die Array- und Indexbezeichnungen zusammen.

Schritt 7: Wählen Sie Parameter nach Workflow-Phase aus

Verwenden Sie eine Anforderungszulassungsliste, anstatt beliebiges Client-JSON direkt an die API zu übergeben. Dadurch wird verhindert, dass nicht unterstützte Felder, übermäßige Batches oder interne Rückruf-URLs die Route erreichen.

Schritt 8: Rückrufe für den Produktionsabschluss verwenden

{
  "model": "grok-imagine-image-2.0",
  "prompt": "A clean ecommerce product scene with soft daylight",
  "callback_url": "https://your-domain.com/webhooks/evolink/image-task"
}

Der aktuelle Vertrag besagt, dass Rückrufe nach der Rechnungsbestätigung gesendet werden, wenn eine Aufgabe abgeschlossen, fehlgeschlagen oder abgebrochen ist. EvoLink wartet bis zu 10 Sekunden und kann einen fehlgeschlagenen Rückruf nach 1, 2 und 4 Sekunden dreimal wiederholen. Eine 2xx-Antwort markiert den erfolgreichen Versand.

Entwerfen Sie den Empfänger idempotent:

1. Authentifizieren Sie die Anfrage mithilfe des Mechanismus, den Ihr EvoLink-Konto und die Webhook-Einrichtung unterstützen.
2. Validieren Sie die Aufgaben-ID und das erwartete Modell.
3. Upsert nach Aufgaben-ID, anstatt bei jeder Lieferung ein neues Ergebnis einzufügen;
4. Rückkehr 2xx nach dauerhafter Persistenz;
5. Langsame Downloads und Überprüfungsarbeiten in eine Warteschlange verschieben;
6. Führen Sie die Abfrage als Wiederherstellungspfad fort, wenn die Webhook-Zustellung nicht bestätigt werden kann.

Die Rückruf-URL muss HTTPS verwenden und darf nicht auf localhost, private IP-Bereiche oder eine interne Dienstadresse verweisen.

Schritt 9: Ergebnisse speichern, bevor sie ablaufen

Fertiggestellte Bild-URLs bleiben 24 Stunden lang verfügbar. Behandeln Sie sie als Übertragungs-URLs und nicht als permanenten Anwendungsspeicher.

Nach Fertigstellung:

1. Überprüfen Sie, ob die Aufgabe zum aktuellen Konto und Job gehört.
2. Laden Sie jeden Artikel in results oder result_data herunter;
3. Inhaltstyp und Dateigröße validieren;
4. Speichern Sie die Datei in Ihrem eigenen Objektspeicher.
5. Speichern Sie die permanente URL und den Inhalts-Hash;
6. Notieren Sie die Generierungsparameter und überprüfen Sie den Status.
7. Wenden Sie Ihre Aufbewahrungs- und Löschrichtlinie auf Referenzeingaben und -ausgaben an.

Schritt 10: Fehler und Abrechnung korrekt behandeln

Die Erstellungsantwort reserviert möglicherweise Credits, aber die Abrechnungswahrheit ist die Terminalnutzung. Gemäß dem Aufgabenvertrag von

Behandeln Sie HTTP-Fehler auf Anforderungsebene vor der Abfrage

Einige Fehler treten auf, bevor eine asynchrone Aufgabe erstellt wird. Die aktuelle API-Referenz dokumentiert diese Antworten auf Anfrageebene:

Schritt 11: Fallback-Routing hinzufügen

Die Integration sollte den Produktauftrag von der anbieterspezifischen Modell-ID trennen:

type ImageRoute = "grok-imagine-image-2.0" | "gpt-image-2";

type ImageJob = {
  prompt: string;
  imageUrls: string[];
  requiresMask: boolean;
  requires4K: boolean;
};

function chooseImageRoute(job: ImageJob): ImageRoute {
  if (job.requiresMask || job.requires4K || job.imageUrls.length > 3) {
    return "gpt-image-2";
  }

  return "grok-imagine-image-2.0";
}

Bei diesem Beispiel handelt es sich um eine Startrichtlinie auf Vertragsebene und nicht um die Behauptung, dass ein Modell bessere Bilder produziert. Fügen Sie Ihre eigenen Akzeptanzdaten, Latenz-, Kosten-, Moderations- und Verfügbarkeitsbeobachtungen hinzu, bevor Sie sinnvollen Datenverkehr weiterleiten.

Checkliste für die Produktionsübergabe

• API-Schlüssel, der in einem serverseitigen Secret-Manager gespeichert ist. – [ ] Die Zulassungsliste für den Anforderungstext entspricht den aktuellen EvoLink-Dokumenten.
• Die Modell-ID ist in der Routenkonfiguration zentralisiert.
• Referenzbilder sind öffentlich, validiert und auf drei begrenzt.
• Multireferenzindizes entsprechen der beibehaltenen Eingabereihenfolge.
• Die Abfrage stoppt, wenn sie abgeschlossen/fehlgeschlagen ist, und verwendet Backoff.
• Anwendungs-Timeouts führen nicht automatisch zu doppelten Aufgaben.
• Die Rückrufverarbeitung ist idempotent und schnell.
• Ergebnisdateien werden vor Ablauf der 24 Stunden kopiert.
• Die endgültige Nutzung wird getrennt von den reservierten Credits gespeichert.
• Rückerstattungen für fehlgeschlagene Aufgaben werden abgeglichen.
• Wiederholbare und nicht wiederholbare Fehler werden getrennt.
• Es gibt eine getestete Fallback-Route für erforderliche Funktionen oder Ausfälle.
• Protokolle schließen API-Schlüssel und vertrauliche Referenz-URLs aus.

Häufig gestellte Fragen

Welcher Endpunkt erstellt eine Grok Imagine Image 2.0-Aufgabe?

Welche Modell-ID soll ich senden?

Wie wechsle ich von der Generierung zur Bearbeitung?

Kann ich Base64-Bilddaten senden?

Nein. Der aktuelle Vertrag akzeptiert öffentlich zugängliche HTTP- oder HTTPS-URLs und unterstützt keine Base64- oder Daten-URLs.

Wie frage ich das Ergebnis ab?

Soll ich eine Umfrage durchführen oder einen Rückruf nutzen?

Verwenden Sie Rückrufe für den normalen Produktionsabschluss und die Abfrage als Wiederherstellungspfad. Ein einfacher serverseitiger Prototyp kann mit Backoff-Polling beginnen.

Wie lange bleiben ausgefüllte Bildlinks gültig?

Die aktuelle Dokumentation besagt 24 Stunden. Kopieren Sie fertige Dateien umgehend in den permanenten Speicher.

Werden fehlgeschlagene Aufgaben in Rechnung gestellt?

Kann ich 4K oder hohe Qualität anfordern?

Nein. Diese Route unterstützt derzeit 1K/2K und Niedrig/Mittel. Verwenden Sie eine andere verifizierte Route, wenn 4K oder Hoch eine zwingende Anforderung ist.

Wo kann ich Grok mit einer anderen Bildroute vergleichen?

Verwenden Sie den Entscheidungsleitfaden [Grok Imagine Image 2.0 vs.

Quellen

• EvoLink Grok Imagine Image 2.0 API-Dokumentation
• EvoLink Task-Status-API-Dokumentation
• Grok Imagine Image 2.0 Release- und Workflow-Leitfaden

Dieses Handbuch spiegelt den am 12. August 2026 verifizierten EvoLink-Vertrag wider. Überprüfen Sie die API-Dokumentation vor dem Versand erneut, insbesondere Modellfelder, Ausgabelimits, Rückrufverhalten und Aufgaben-Antwort-Schemas.