Comment utiliser l'API Grok Imagine Image 2.0 sur EvoLink

Ce que vous construirez

À la fin du guide, votre application pourra :

1. créer une tâche de conversion texte-image ;
2. passer à l'édition de références sans modifier les ID de modèle ;
3. utiliser des références indexées dans une invite multi-images ;
4. suivre une tâche asynchrone par ID ;
5. accepter un rappel d'achèvement en toute sécurité ;
6. conserver les résultats avant l'expiration de leurs URL de 24 heures ;
7. concilier les remboursements de l'utilisation finale et des tâches ayant échoué ;
8. passer à une route de secours lorsque la charge de travail ou le résultat de la tâche l'exige.

Avant de commencer

Étape 1 : conserver la clé API côté serveur

Pour un test shell, définissez la clé dans une variable d'environnement :

export EVOLINK_API_KEY="your_api_key"

Étape 2 : créer une tâche de conversion texte-image

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"
  }
}

La valeur de réservation ci-dessus est un exemple de documentation, et non une promesse de prix ni le montant final. Utilisez la page de modèle actuelle pour la tarification en direct et la réponse à la tâche du terminal pour l'utilisation finale.

Étape 3 : interroger la tâche asynchrone

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
    }
  }
}

Ces valeurs numériques sont des exemples de valeurs de réponse. Enregistrez les valeurs renvoyées par votre propre tâche de terminal ; n'utilisez pas cet exemple pour calculer la facturation client.

Étape 4 : ajouter un sondage contrôlé

L'interrogation doit s'arrêter sur l'état d'un terminal, reculer entre les requêtes et imposer un délai d'attente d'application. L'exemple TypeScript côté serveur suivant maintient le flux de travail des tâches explicite :

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");
}

Un délai d'attente d'application ne constitue pas une preuve que la tâche en amont a échoué. Avant de réessayer la génération, interrogez à nouveau la tâche d'origine ou utilisez une stratégie d'idempotence dans votre propre couche de tâches. Sinon, un délai d'attente client peut créer des tâches facturables en double.

Étape 5 : passer à l'édition à référence unique

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
  }'

Votre application doit valider le nombre, le protocole, le type de fichier et l'accessibilité du serveur avant de créer une tâche payante. Une URL qui fonctionne dans un navigateur connecté peut toujours être inaccessible au service de génération.

Étape 6 : composer avec plusieurs références

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
  }'

Stockez l'ordre exact du tableau avec l'invite. Si une interface utilisateur permet à quelqu'un de réorganiser les téléchargements, mettez à jour les étiquettes du tableau et de l'index ensemble.

Étape 7 : choisissez les paramètres par étape du workflow

Utilisez une liste d'autorisation de requête plutôt que de transmettre le JSON arbitraire du client directement à l'API. Cela empêche les champs non pris en charge, les lots excessifs ou les URL de rappel internes d'atteindre la route.

Étape 8 : utilisez les rappels pour terminer la production

{
  "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"
}

Le contrat actuel stipule que les rappels sont envoyés après la confirmation de la facturation lorsqu'une tâche est terminée, échouée ou annulée. EvoLink attend jusqu'à 10 secondes et peut réessayer un rappel ayant échoué trois fois après 1, 2 et 4 secondes. Une réponse 2xx marque la livraison réussie.

Concevoir le récepteur pour qu'il soit idempotent :

1. authentifiez la demande à l'aide du mécanisme pris en charge par votre compte EvoLink et la configuration de votre webhook ;
2. valider l'ID de la tâche et le modèle attendu ;
3. upsert par ID de tâche plutôt que d'insérer un nouveau résultat à chaque livraison ;
4. renvoyer 2xx après une persistance durable ;
5. déplacer les téléchargements lents et réviser le travail vers une file d'attente ;
6. continuez à interroger comme chemin de récupération lorsque la livraison du webhook ne peut pas être confirmée.

L'URL de rappel doit utiliser HTTPS et ne peut pas pointer vers un hôte local, des plages d'adresses IP privées ou une adresse de service interne.

Étape 9 : enregistrez les résultats avant leur expiration

Les URL des images complétées restent disponibles pendant 24 heures. Traitez-les comme des URL de transfert et non comme un stockage d'application permanent.

Une fois terminé :

1. vérifier que la tâche appartient au compte courant et à l'emploi ;
2. téléchargez chaque élément dans results ou result_data ;
3. valider le type de contenu et la taille du fichier ;
4. stockez le fichier dans votre propre stockage d'objets ;
5. enregistrez l'URL permanente et le hachage du contenu ;
6. enregistrer les paramètres de génération et examiner l'état ;
7. appliquez votre politique de conservation et de suppression aux entrées et sorties de référence.

Étape 10 : gérer correctement les échecs et la facturation

Gérer les erreurs HTTP au niveau de la requête avant l'interrogation

Certains échecs se produisent avant la création d'une tâche asynchrone. La référence actuelle de l'API documente ces réponses au niveau des requêtes :

Étape 11 : ajouter un routage de secours

L'intégration doit séparer la tâche du produit de l'ID de modèle spécifique au fournisseur :

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";
}

Cet exemple est une politique de départ au niveau du contrat, et non une affirmation selon laquelle un modèle produit de meilleures images. Ajoutez vos propres données d'acceptation, de latence, de coût, de modération et de disponibilité avant d'acheminer un trafic significatif.

Liste de contrôle du transfert de production

• Clé API stockée dans un gestionnaire de secrets côté serveur.
• La liste autorisée du corps de la demande correspond aux documents EvoLink actuels.
• L'ID du modèle est centralisé dans la configuration de la route.
• Les images de référence sont publiques, validées et limitées à trois.
• Les index multi-références correspondent à l'ordre d'entrée persistant.
• L'interrogation s'arrête en cas de réussite/d'échec et utilise l'interruption.
• Les délais d'attente des applications ne créent pas automatiquement des tâches en double.
• Le traitement des rappels est idempotent et rapide.
• Les fichiers de résultats sont copiés avant l'expiration des 24 heures.
• L'utilisation finale est stockée séparément des crédits réservés.
• Les remboursements de tâches ayant échoué sont rapprochés.
• Les erreurs réessayables et non réessayables sont séparées.
• Une route de secours testée existe pour les capacités requises ou les pannes.
• Les journaux excluent les clés API et les URL de référence sensibles.

Questions fréquemment posées

Quel point de terminaison crée une tâche Grok Imagine Image 2.0 ?

Quel identifiant de modèle dois-je envoyer ?

Comment passer de la génération à l'édition ?

Puis-je envoyer des données d'image base64 ?

Non. Le contrat actuel accepte les URL HTTP ou HTTPS accessibles au public et ne prend pas en charge les URL base64 ou de données.

Comment interroger le résultat ?

Dois-je interroger ou utiliser un rappel ?

Utilisez les rappels pour l’achèvement normal de la production et l’interrogation comme chemin de récupération. Un simple prototype côté serveur peut commencer par une interrogation d'interruption.

Combien de temps les liens d'images complétés restent-ils valides ?

La documentation actuelle indique 24 heures. Copiez rapidement les fichiers terminés vers un stockage permanent.

Les tâches échouées sont-elles facturées ?

Puis-je demander la 4K ou la haute qualité ?

Non. Cette route prend actuellement en charge 1K/2K et Low/Medium. Utilisez une autre route vérifiée lorsque 4K ou High est une exigence stricte.

Où puis-je comparer Grok avec une autre route d'images ?

Utilisez le [Guide de décision Grok Imagine Image 2.0 vs GPT Image 2] (/blog/grok-imagine-image-2-0-vs-gpt-image-2), puis validez les deux avec votre propre ensemble de tests couplés.

##Sources

• Documentation API EvoLink Grok Imagine Image 2.0
• Documentation de l'API sur l'état des tâches EvoLink
• Guide de version et de flux de travail Grok Imagine Image 2.0

Ce guide reflète le contrat EvoLink vérifié le 12 août 2026. Revérifiez la documentation de l'API avant l'expédition, en particulier les champs de modèle, les limites de sortie, le comportement de rappel et les schémas tâche-réponse.