API imagen-4.0-fast : une requête texte-vers-image qui fonctionne réellement

Imagen 4 Fast est le palier de rapidité de la série Google Imagen 4 et, sur hiapi, il réalise la génération texte-vers-image via la même API de tâches asynchrones unifiée que tous les autres modèles d'image. Ce guide vous fournit une requête qui fonctionne réellement : un véritable appel curl, une boucle de polling en Python, le schéma d'entrée fermé exact, et les cas d'erreur validés en production. Tout ce qui suit a été exécuté contre le point de terminaison de production avant publication ; le taskId et l'URL de sortie des exemples proviennent de cette exécution.

Ce que vous allez réaliser

Un seul appel transforme un prompt texte en une image finie : soumettez une tâche à POST /v1/tasks, interrogez-la jusqu'à son achèvement, puis lisez l'URL de l'image. Vous avez besoin d'une clé API hiapi (créez-la dans la console et conservez un peu de crédit à l'usage dans votre compte — voir la tarification). Aucun SDK n'est nécessaire ; chaque exemple ici est du HTTP pur.

Requête minimale fonctionnelle (curl)

Créez la tâche. L'identifiant du modèle est imagen-4.0-fast, et sur ce palier aspect_ratio est obligatoire (explications détaillées plus bas) :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen-4.0-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

L'appel de création ne renvoie qu'un identifiant de tâche — pas l'image :

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

Interroger le résultat (Python)

Une fois le taskId obtenu, interrogez GET /v1/tasks/<id> jusqu'à ce que le statut atteigne un état terminal. Voici la boucle que j'ai réellement exécutée :

import os, time, requests

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

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen-4.0-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

Lors de mon exécution, le statut est passé par handling → archiving → success en environ 12 secondes, et la réponse finale était :

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen-4.0-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

Une tâche renvoie une image WebP. Le statut archiving est normal — il reste brièvement puis bascule vers success.

Schéma d'entrée (ce que le serveur accepte réellement)

L'objet input est un schéma fermé. Il n'accepte que les champs suivants :

Champ	Type	Obligatoire	Description
prompt	string	Oui	Non vide ; une chaîne vide renvoie minLength: got 0, want 1.
aspect_ratio	enum	Oui	L'une des valeurs 1:1, 16:9, 9:16, 3:4, 4:3, auto. Aucune valeur par défaut.
seed	integer	Non	Pour des exécutions reproductibles. Doit être un nombre JSON, pas une chaîne.
negative_prompt	string	Non	Décrit ce que l'on souhaite éviter dans l'image.

Ce modèle n'a pas de champ resolution ni size — la taille de sortie suit aspect_ratio. Tout champ hors de ce tableau est rejeté.

Cas d'erreur vérifiés (les pièges)

Ce ne sont pas des suppositions — chacun est une vraie réponse 400 capturée contre le point de terminaison de production.

1. aspect_ratio manquant. C'est le piège numéro un lorsque vous copiez un extrait de code depuis le palier Imagen 4 de base ou Ultra, où aspect_ratio vaut 1:1 par défaut. Sur Fast, il n'y a pas de valeur par défaut :

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed envoyé sous forme de chaîne. Passez-le sous forme de nombre :

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. Champ inconnu (ici resolution) — le schéma fermé rejette tout contenu superflu :

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

Remarquez la forme : un échec de validation est un HTTP 400, avec error_code: "INVALID_REQUEST", sans taskId, et le message agrège chaque erreur de champ en une seule chaîne séparée par ; — lisez donc le message entier, pas seulement la première phrase.

Fast comparé aux autres paliers de la série Imagen 4

hiapi héberge les trois paliers Imagen 4 sur exactement la même API de tâches ; seul l'identifiant model diffère, de sorte que le corps de requête ci-dessus fonctionne pour tous les paliers :

• imagen-4.0-fast — le palier de rapidité (page du modèle), également l'option la moins coûteuse de la série. Idéal pour l'itération de prompts, l'exploration de concepts et l'exploration en masse, c'est-à-dire générer beaucoup de candidats et n'en garder que quelques-uns.
• imagen-4.0 — le palier Imagen 4 standard.
• imagen-4.0-ultra — le palier de détail maximal, pour les rendus de qualité livraison.

Un workflow pratique : prototyper sur Fast, puis remplacer la chaîne model par imagen-4.0-ultra pour le rendu final, sans modifier le reste du code. Comparez les prix actuels par image sur la page de tarification.

Considérations pour la production

• Polling vs. webhook. La boucle ci-dessus est du polling. En production, l'API de tâches hiapi prend aussi en charge les webhooks : ajoutez un objet callback de premier niveau (au même niveau que model/input) contenant url et when: "final", et hiapi enverra en POST les détails de la tâche lorsque celle-ci atteindra un état terminal. Avant de vous y fier, lisez la documentation de l'API asynchrone pour connaître les conventions de livraison et de nouvelle tentative.
• Ne soumettez pas à nouveau en cas de réseau instable. Chaque création de tâche renvoie un nouveau taskId — il n'y a pas de déduplication des prompts. Si une requête de polling échoue brièvement, interrogez à nouveau le taskId que vous avez déjà enregistré ; ne refaites un POST que si vous n'avez jamais reçu de taskId.
• Les URL de sortie expirent. output[].url se trouve sur temp.hiapi.ai et son expireAt est d'environ 7 jours (l'exemple ci-dessus expire le 2026-10-28). Téléchargez immédiatement les octets dans votre propre stockage ; ne faites pas de hotlinking.

Contenus associés

• Page du modèle Imagen 4 Fast
• Imagen 4 Ultra — palier de détail maximal, structure de requête identique
• Imagen 4 (version de base)
• Documentation de l'API de tâches asynchrones unifiée
• Tarification

Questions fréquentes

Imagen 4 Fast nécessite-t-il un point de terminaison ou un SDK différent ? Non. C'est simplement POST /v1/tasks avec "model": "imagen-4.0-fast" — le même point de terminaison que tous les modèles d'image et de vidéo de hiapi. Changez de palier en modifiant l'identifiant du modèle.

Pourquoi ma requête renvoie-t-elle une 400 avec « missing required field aspect_ratio » ? Fast n'a pas de ratio d'aspect par défaut (contrairement aux paliers de base et Ultra). Envoyez toujours aspect_ratio parmi l'énumération 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto.

Puis-je définir la résolution ou la taille de l'image ? Non — ce modèle n'a pas de champ resolution ni size ; la taille de sortie suit aspect_ratio. Envoyer resolution renvoie additional properties 'resolution' not allowed.

seed est-il une chaîne ou un nombre ? Un nombre. "seed": 7 fonctionne ; "seed": "7" renvoie seed: got string, want integer.

Quelle est la durée de validité de l'URL de sortie ? Environ 7 jours (expireAt). Téléchargez et stockez immédiatement.