API imagen-4.0-ultra : une requête de génération d'image texte-vers-image fonctionnelle

Imagen 4 Ultra est la version la plus détaillée de la gamme Google Imagen 4. Sur hiapi, comme tous les autres modèles d'image, elle exécute la génération texte-vers-image via la même API de tâches asynchrones unifiée. Ce guide présente une requête réellement fonctionnelle : un véritable appel curl, une boucle de polling en Python, les paramètres réellement acceptés par le serveur, et des cas d'erreur vérifiés par de vraies requêtes. Tout ce qui suit a été exécuté et validé sur le point de terminaison de production avant publication ; l'exemple de taskId et l'URL de sortie proviennent de cette exécution.

Ce que vous allez construire

Un seul appel transforme un prompt textuel en image finie : soumettez une tâche via POST /v1/tasks, interrogez jusqu'à l'achèvement, puis lisez l'URL de l'image dans output[0].url. Vous aurez besoin d'une clé API hiapi — récupérez-la depuis votre tableau de bord et exportez-la :

export HIAPI_API_KEY="your-hiapi-key"

Exemple minimal fonctionnel (curl)

Le modèle accepte prompt et, en option, aspect_ratio. Créez une tâche :

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-ultra",
    "input": {
      "prompt": "Macro product photo of a matte ceramic coffee mug on a pale oak table, soft window light from the left, shallow depth of field, a few coffee beans in the foreground, no text, no logos",
      "aspect_ratio": "4:3"
    }
  }'

L'appel de création renvoie immédiatement un identifiant de tâche — la génération se poursuit en arrière-plan :

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

Interrogez la tâche avec l'identifiant renvoyé :

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Lorsque status vaut success, l'image se trouve dans output[0].url :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5CVC8R62M0Z7CCM8WB38B61",
    "model": "imagen-4.0-ultra",
    "status": "success",
    "storage": "temp",
    "created": 1792506471,
    "completed": 1792506479,
    "output": [
      {
        "artifactId": "279760",
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5CVC8R62M0Z7CCM8WB38B61-0.webp",
        "expireAt": 1793111279
      }
    ]
  },
  "message": "success"
}

Cette exécution s'est terminée en environ 8 secondes et a renvoyé un WebP (et non un PNG/JPEG). L'URL pointe vers un stockage temporaire ("storage": "temp"), avec expireAt défini à 7 jours plus tard — téléchargez-la rapidement, ne faites pas de hotlink.

En production : Python avec boucle de polling

La réponse de création ne contient pas l'image — uniquement taskId. Une intégration réelle soumet d'abord, puis interroge (ou utilise un callback). Ce script effectue l'aller-retour complet et télécharge immédiatement le résultat, car l'URL est temporaire :

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="1:1", negative_prompt=None, seed=None):
    body = {"model": "imagen-4.0-ultra", "input": {"prompt": prompt, "aspect_ratio": aspect_ratio}}
    if negative_prompt:
        body["input"]["negative_prompt"] = negative_prompt
    if seed is not None:
        body["input"]["seed"] = str(seed)  # seed is a STRING, not a number

    r = requests.post(API, headers=HEADERS, json=body, timeout=60)
    r.raise_for_status()
    created = r.json()
    if created.get("code") != 200:
        raise RuntimeError(f"create rejected: {created}")
    task_id = created["data"]["taskId"]

    # Poll. Statuses other than success/fail (e.g. queued, running, archiving) mean "keep waiting".
    for _ in range(60):
        time.sleep(3)
        try:
            d = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            continue  # tolerate a transient read; re-poll the same id
        status = d.get("status")
        if status == "success":
            return d["output"][0]["url"]
        if status in ("fail", "failed", "error"):
            raise RuntimeError(f"task failed: {d}")
    raise TimeoutError(f"task {task_id} did not finish in time")

url = generate(
    "A high-detail aerial landscape of terraced rice fields at golden hour, long shadows",
    aspect_ratio="16:9",
)
img = requests.get(url, timeout=60).content
open("out.webp", "wb").write(img)
print(f"saved {len(img)} bytes from {url}")

Points importants en production :

• Polling vs callback. L'exemple ci-dessus utilise le polling. Pour éviter le polling, joignez un objet callback de premier niveau ({"url": "...", "when": "final"}) ; hiapi vous enverra une requête POST lorsque la tâche atteindra un état terminal. Le contrat de callback est décrit dans la documentation de l'API asynchrone unifiée.
• Réinterrogez l'identifiant enregistré, ne recréez pas. La lecture d'une tâche est idempotente ; en cas de connexion interrompue, réessayez GET /v1/tasks/<id>, ne faites jamais un nouveau POST (cela facturerait une image supplémentaire).
• Téléchargez dès le succès. output[0].url est temporaire (TTL de 7 jours lors de cette exécution). Récupérez les octets et poussez-les vers votre propre stockage.

Paramètres réellement acceptés par ce modèle

imagen-4.0-ultra ne prend en charge que la génération texte-vers-image — pas d'image de référence (confirmé sur la page du modèle ; cette exécution n'a testé que le texte-vers-image). Le schéma d'entrée est fermé : les champs inconnus sont rejetés, impossible donc de faire passer des paramètres supplémentaires en douce.

Champ	Type	Requis	Description
prompt	string	oui	1 à 5 000 caractères. Une chaîne vide échoue (minLength: got 0, want 1).
aspect_ratio	enum	non	L'une des valeurs 1:1, 16:9, 9:16, 3:4, 4:3, auto. Par défaut 1:1.
negative_prompt	string	non	Jusqu'à 5 000 caractères ; décrit ce qu'il faut exclure.
seed	string	non	Jusqu'à 500 caractères. C'est une chaîne — un nombre sera rejeté.

Une requête génère exactement une image.

Cas d'erreur vérifiés

Ces cas ont été produits sur le vrai point de terminaison, votre gestion des erreurs peut donc s'y fier. Une requête rejetée renvoie un HTTP 400, avec une enveloppe plate et sans taskId :

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: aspect_ratio: value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'"}

Quelques comportements à prendre en compte dans votre code :

• Le validateur signale toutes les erreurs de champ en une fois, reliées par ; . Si vous passez un nombre pour seed et un aspect_ratio invalide, vous obtenez les deux dans un seul message : invalid input: seed: got number, want string; aspect_ratio: value must be one of .... Ne supposez pas qu'une réponse ne contient qu'une seule erreur.
• Un champ inconnu fait échouer toute la requête, avec l'erreur <root>: additional properties '<name>' not allowed. Le schéma est fermé.
• Un prompt vide échoue avec l'erreur prompt: minLength: got 0, want 1.
• Une create réussie renvoie code: 200 avec data.taskId ; un rejet renvoie data: null. Branchez votre code sur ce critère avant de tenter de lire l'identifiant de tâche.

Quel niveau d'Imagen 4 appeler ?

imagen-4.0-ultra est le plus haut des trois niveaux ; choisissez selon la tâche, pas par habitude (le format, le prompt négatif et la graine n'affectent pas le prix — voir la tarification) :

• Imagen 4 Fast — le moins cher, idéal pour des ébauches rapides et l'exploration en masse de directions.
• Imagen 4 — le niveau intermédiaire du quotidien, adapté aux images de produit, de lifestyle et de contenu.
• Imagen 4 Ultra (ce modèle) — le plus cher des trois, positionné sur le détail de qualité finale : textures macro, rendu des matériaux et typographie, pour les cas où l'image finale doit résister à l'examen. Choisissez Ultra lorsque la sortie est livrable telle quelle ; utilisez Fast ou le niveau de base pour itérer.

Liens utiles

• Page du modèle Imagen 4 Ultra — schéma en direct, exemples et tarification.
• Documentation de l'API asynchrone unifiée — création/liste/récupération de tâches et contrat de callback.
• Démarrage rapide — authentifiez-vous et exécutez votre première tâche en quelques minutes.
• Tarification — coût par image pour chaque niveau d'Imagen 4.

FAQ

Combien d'images une requête renvoie-t-elle ? Une. Lors de l'exécution vérifiée, le tableau output ne contenait qu'une seule entrée.

Quel est le format de sortie ? WebP. Le fichier renvoyé est un .webp sur temp.hiapi.ai.

Combien de temps l'URL de sortie reste-t-elle valide ? Environ 7 jours — expireAt est fixé à 7 jours après l'achèvement. Considérez-la comme une ressource temporaire et téléchargez immédiatement.

Peut-on envoyer une image de référence ? Non. imagen-4.0-ultra ne prend en charge que la génération texte-vers-image ; la page du modèle indique que les images de référence ne sont pas prises en charge.

Pourquoi ma requête renvoie-t-elle l'erreur "additional properties not allowed" ? Le schéma d'entrée est fermé. N'envoyez que prompt, aspect_ratio, negative_prompt et seed ; toute autre clé fait échouer l'ensemble de la requête.

Le prompt négatif, la graine ou le format changent-ils le prix ? Non. La facturation se fait à l'image ; ces paramètres n'ont aucun impact sur le coût.