Générer des images

POST /v1/images/generations

Génère des images. Synchrone par défaut : l’appel attend que l’image soit prête et répond dans la même forme que le point d’accès images/generations d’OpenAI, si bien que le SDK OpenAI et les passerelles de relais fonctionnent sans réglage. Avec async: true vous recevez immédiatement un id de tâche et lisez le résultat via GET /v1/tasks/{id}. Avec n supérieur à 1, n tâches indépendantes sont créées, chacune facturée séparément.

Paramètres

Paramètre	Type	Description
prompt	string	Obligatoire. Ce qu’il faut dessiner
model	string	id de modèle issu de /v1/models. Sinon, modèle par défaut
n	integer	Nombre d’images, de 1 à 4. Par défaut 1
size	string	Format 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4. Par défaut 1:1. Les écritures en pixels comme 1024x1024 ou 1792x1024 sont acceptées et ramenées au format le plus proche
quality	string	Qualité 1k \| 2k \| 4k. Par défaut 1k, remplacée par spec. Les écritures OpenAI sont acceptées : standard / low / auto valent 1k, medium / hd / high valent 2k
spec	string	Clé de palier issue de specs[].key du modèle
reference_images	string[]	URLs de référence. Ce qui dépasse max_reference_images est ignoré
async	boolean	false par défaut : on attend l’image. true renvoie aussitôt un objet de tâche, à vous d’interroger /v1/tasks/{id}

Une valeur non reconnue ne fait pas échouer la requête : on revient à la valeur par défaut (un size inconnu est simplement rendu en 1:1). Seuls un prompt vide, un contenu bloqué, un quota atteint ou des crédits insuffisants provoquent une erreur. response_format n’est pas pris en charge : les résultats arrivent toujours sous forme d’url.

Requête (synchrone)

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "une rue cyberpunk sous la pluie la nuit, reflets de néons",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'

Réponse (synchrone)

json

{
  "created": 1786000246,
  "data": [
    { "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "une rue cyberpunk sous la pluie la nuit, reflets de néons" }
  ],
  "id": "2608101909450810293847",
  "object": "image.generation",
  "model": "img-std-1",
  "status": "succeeded",
  "n": 1,
  "credits": 10,
  "tasks": [
    {
      "id": "2608101909450810293847",
      "status": "succeeded",
      "data": [{ "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "une rue cyberpunk sous la pluie la nuit, reflets de néons" }]
    }
  ]
}

Champ	Description
created	Horodatage de la réponse
data	Résultats, chacun avec url et revised_prompt. Plusieurs entrées si n > 1
id	Tâche principale (avec n > 1, la première sous-tâche)
status	succeeded — y compris en succès partiel : comparez vous-même la taille de data à n
credits	Total des crédits débités
tasks	Toutes les sous-tâches, chacune avec son error et son résultat

Un appel synchrone garde la connexion ouverte, souvent plus de 30 secondes par image : portez le délai d’attente du client à 300 secondes. Au-delà de 300 secondes le serveur renvoie 504 generation_timeout ; la tâche continue et les crédits ne sont pas remboursés, récupérez donc le résultat plus tard via /v1/tasks/{id} avec l’id figurant dans le message. Si toutes les images échouent, vous obtenez 502 generation_failed et les crédits sont remboursés automatiquement.

Mode asynchrone

Pour les lots, une forte concurrence ou des appelants sensibles à la latence : la réponse arrive aussitôt, status vaut queued et data est vide.

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "une rue cyberpunk sous la pluie la nuit, reflets de néons",
    "size": "16:9",
    "quality": "2k",
    "n": 1,
    "async": true
  }'

json

{
  "id": "2608101909450810293847",
  "object": "image.generation",
  "created": 1786000185,
  "model": "img-std-1",
  "status": "queued",
  "n": 1,
  "credits": 10,
  "tasks": [
    { "id": "2608101909450810293847", "status": "queued", "data": [] }
  ],
  "data": []
}

Avec n > 1, parcourez tasks. N’interroger que id fait silencieusement perdre les autres images.