Comment utiliser gpt-image-2-beta via l'API hiapi : paramètres, code et exemples exécutables

gpt-image-2-beta est la voie minimaliste à tarif fixe pour accéder à GPT Image 2 sur hiapi : deux champs d'entrée, un seul prix, aucun réglage de ratio d'aspect ni de qualité. Ce guide présente l'exemple minimal exécutable, la structure exacte des paramètres (confirmée en interrogeant le point de terminaison en ligne), ainsi que la comparaison avec la voie par défaut gpt-image-2/text-to-image, pour vous aider à déterminer quand utiliser l'une ou l'autre.

Prérequis

Vous devez obtenir une clé API depuis la page API Keys du tableau de bord hiapi — la clé commence par sk-. Le prix actuel par image est indiqué sur la page du modèle gpt-image-2-beta et sur la page de tarification.

Comme tous les modèles d'image sur hiapi, ce modèle fonctionne sur le point de terminaison unifié de tâches asynchrones :

• POST https://api.hiapi.ai/v1/tasks — crée une tâche de génération
• GET https://api.hiapi.ai/v1/tasks/{taskId} — interroge l'état de la tâche

Ce qui distingue la voie beta

gpt-image-2/text-to-image (la voie par défaut) accepte aspect_ratio + resolution et facture selon le palier de résolution (0,03 $ pour 1K, jusqu'à 0,06 $ pour 4K). gpt-image-2-beta réduit tout cela à un prix fixe unifié de 0,02 $ par image et à un champ size optionnel — une chaîne de dimensions en pixels littérales, comme "1024x1024" ou "1600x900", et non un ratio. Si vous omettez complètement size, le modèle revient à sa taille de sortie par défaut.

Le compromis : vous abandonnez le contrôle fin du ratio et de la résolution en échange d'un prix plus bas et plus simple. C'est adapté lorsque vous avez simplement besoin de « générer une image à moindre coût » sans vous soucier de la composition exacte.

Exemple minimal exécutable (curl)

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

L'image terminée se trouve dans data.output[0].url. Cette URL a une durée de validité courte expireAt — téléchargez-la immédiatement et réhébergez-la sur votre propre stockage ; ne la liez pas directement dans du contenu de production.

Image d'exemple générée par l'appel curl ci-dessus (avec un autre prompt), en utilisant size: "1024x1024".

Python : créer + interroger + enregistrer sur disque

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

Référence des paramètres

L'objet input de gpt-image-2-beta n'accepte que deux champs — la structure est en additionalProperties: false, donc tout autre contenu est directement rejeté plutôt que silencieusement ignoré.

Champ	Type	Obligatoire	Description
prompt	string	Oui	Description textuelle de l'image à générer.
size	string	Non	Dimensions en pixels littérales, par exemple "1024x1024", "1600x900". Ce n'est pas un mot-clé de ratio d'aspect. Si omis, la taille de sortie par défaut du modèle est utilisée.

Éléments non pris en charge (et erreurs obtenues)

La structure beta n'accepte aucun des champs utilisés par la voie par défaut gpt-image-2/text-to-image ou par l'API Images d'OpenAI — aspect_ratio, resolution, quality, background, moderation, output_format, output_compression, n, user ou style. L'envoi de l'un d'entre eux renvoie immédiatement un HTTP 400, par exemple :

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

Si vous migrez du code depuis la voie par défaut ou depuis l'API Images d'OpenAI, réduisez-le d'abord à prompt + size, puis pointez vers gpt-image-2-beta.

Tarification : beta vs par défaut vs @ext

Voie	Prix	Contrôles
gpt-image-2-beta	0,02 $/image fixe	size uniquement (dimensions en pixels)
gpt-image-2/text-to-image (par défaut)	0,03 $ (1K) / 0,04 $ (2K) / 0,06 $ (4K)	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	0,007 $–0,76 $, selon qualité × résolution	16 ratios d'aspect, paliers de qualité

Avant de choisir une voie en production, consultez la page de tarification — les prix de tout modèle donné peuvent changer.

Conseils pour développer sur la voie beta

• Considérez la liste de champs ci-dessus comme la convention actuelle, non comme une convention permanente. La structure ou la tarification de la voie beta est plus susceptible d'être ajustée que celle de la voie par défaut — si vous en dépendez en production, consultez régulièrement la page du modèle.
• Comme size est optionnel, si votre mise en page dépend d'une taille spécifique, passez-la toujours explicitement — ne comptez pas sur le fait que la valeur par défaut actuelle reste inchangée.
• Gérez status: "fail" comme pour tout autre modèle d'image hiapi : lisez task.error.code / task.error.message et réessayez avec un backoff, plutôt que de supposer que chaque échec est temporaire.

Questions fréquentes

gpt-image-2-beta et gpt-image-2/text-to-image sont-ils le même modèle ? Il s'agit du même modèle GPT Image 2 sous-jacent, mais la voie API diffère — la voie beta échange le contrôle des paramètres contre un prix fixe plus bas.

Puis-je demander un ratio d'aspect spécifique ? Pas directement. Choisissez une chaîne size ayant le ratio largeur:hauteur souhaité (par exemple "1600x900" pour du 16:9), plutôt que d'utiliser l'énumération aspect_ratio.

Que se passe-t-il si je ne passe pas du tout size ? La tâche réussit quand même — le modèle utilise sa propre taille de sortie par défaut.

Pour aller plus loin

Pour la voie complète avec contrôle explicite du ratio d'aspect et de la résolution, consultez Comment utiliser gpt-image-2/text-to-image via l'API hiapi. Prêt à essayer vous-même ? Obtenez une clé depuis la page API Keys et exécutez l'exemple curl ci-dessus.