Guide API Seedream 5.0 Pro : générer et modifier des images avec du code

Guide API Seedream 5.0 Pro

L’API Seedream 5.0 Pro permet aux développeurs d’accéder au modèle phare de génération et de modification d’images de ByteDance via un workflow asynchrone conçu pour la production. Ce guide explique comment envoyer des tâches de conversion texte-image et de modification d’images avec Poyo.ai, puis récupérer le résultat avec un polling ou un webhook.

Le tarif actuel est de 15 crédits, soit environ $0.075 par image générée, pour les deux variantes du modèle.

Modèles API et paramètres

Workflow	Identifiant du modèle
Texte vers image	`seedream-5.0-pro`
Modification d’image	`seedream-5.0-pro-edit`

Les entrées prises en charge incluent :

prompt : instruction obligatoire de génération ou de modification
size : préréglage de résolution comme 1K ou 2K, ou ratio d’aspect comme 1:1, 4:3, 3:4, 16:9 ou 9:16
n : nombre d’images à générer
output_format : jpeg ou png
image_urls : images de référence pour le modèle d’édition, jusqu’à 10
callback_url : endpoint HTTPS facultatif pour les notifications de fin de traitement

Consultez la référence API en direct pour le schéma actuel.

1. Créer une clé API

Créez un compte Poyo.ai, ouvrez la page Gestion des clés API, puis stockez la clé dans une variable d’environnement. N’exposez jamais une clé de production dans du code côté navigateur et ne la committez pas dans Git.

export POYO_API_KEY="your-api-key"

2. Envoyer une requête texte vers image

Toutes les tâches utilisent l’endpoint d’envoi unifié :

POST https://api.poyo.ai/api/generate/submit

cURL

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro",
    "callback_url": "https://example.com/webhooks/poyo",
    "input": {
      "prompt": "Editorial science magazine cover about clean energy cities, title \"THE ELECTRIC CITY\", structured grid, accurate icons, dark navy and electric green palette",
      "size": "3:4",
      "n": 1,
      "output_format": "png"
    }
  }'

La réponse contient un identifiant de tâche :

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-07-16T10:10:00"
  }
}

3. Appeler Seedream 5.0 Pro avec JavaScript

const API_URL = 'https://api.poyo.ai/api/generate/submit';

async function generateSeedreamImage(prompt) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POYO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'seedream-5.0-pro',
      input: {
        prompt,
        size: '2K',
        n: 1,
        output_format: 'png',
      },
    }),
  });

  const payload = await response.json();
  if (!response.ok || payload.code !== 200) {
    throw new Error(payload.error?.message || 'Seedream request failed');
  }
  return payload.data.task_id;
}

Utilisez 2K lorsque la résolution est plus importante qu’un ratio fixe. Utilisez une valeur de ratio d’aspect lorsque le format de placement constitue la contrainte principale.

4. Appeler Seedream 5.0 Pro avec Python

import os
import requests

API_URL = "https://api.poyo.ai/api/generate/submit"

def generate_seedream_image(prompt: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "seedream-5.0-pro",
            "input": {
                "prompt": prompt,
                "size": "16:9",
                "n": 1,
                "output_format": "jpeg",
            },
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("error", {}).get("message", "Request failed"))
    return payload["data"]["task_id"]

5. Modifier des images avec plusieurs références

Changez l’identifiant du modèle et fournissez image_urls. Indiquez au modèle le rôle de chaque image de référence.

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro-edit",
    "input": {
      "prompt": "Use the room from reference 1. Replace only the chair with the chair from reference 2. Put the logo from reference 3 on the wall. Preserve the original camera, windows, floor, and afternoon lighting.",
      "image_urls": [
        "https://example.com/room.jpg",
        "https://example.com/chair.png",
        "https://example.com/logo.png"
      ],
      "size": "16:9",
      "n": 1,
      "output_format": "png"
    }
  }'

Pour des modifications fiables, séparez le prompt en trois éléments : les rôles des références, les changements demandés et les contraintes de conservation.

6. Récupérer le résultat

L’envoi est asynchrone. Après réception de task_id, vous pouvez :

interroger l’endpoint unifié de statut des tâches de Poyo.ai ; ou
fournir callback_url et traiter le webhook de fin de traitement.

Suivez la documentation de gestion des tâches pour connaître la route de statut actuelle et l’objet de réponse. En production, utilisez un backoff exponentiel plutôt qu’un polling continu.

Gestion des erreurs

Gérez explicitement les cas suivants :

400 : paramètres de modèle invalides, tailles non prises en charge, URL d’images inaccessibles ou JSON mal formé
401 : clé API absente ou invalide
tâche asynchrone échouée : la génération a échoué après une soumission valide
nouvelle tentative du webhook : le même événement de fin peut être envoyé plusieurs fois

Associez l’identifiant de tâche à votre identifiant de tâche interne, rendez le traitement des webhooks idempotent et journalisez les messages d’erreur du fournisseur sans enregistrer de secrets.

Checklist de production

Conservez les clés API côté serveur.
Validez la longueur du prompt et les types d’URL d’image avant l’envoi.
Utilisez des images de référence HTTPS accessibles par le service de génération.
Définissez des délais d’expiration pour les appels de soumission.
Réessayez les erreurs réseau temporaires, mais ne relancez pas aveuglément les requêtes invalides.
Suivez les coûts avec number of requested outputs × 15 credits au tarif actuel.
Vérifiez les textes générés, les détails des produits et les affirmations factuelles avant publication.
Ajoutez une modération de contenu adaptée à votre produit et à votre marché.

Quand utiliser Pro plutôt que Lite

Utilisez Seedream 5.0 Pro pour les designs structurés, les mises en page complexes, les textes multilingues et les modifications contrôlées. Utilisez Seedream 5.0 Lite pour les tâches d’image à moindre coût et à plus grande échelle lorsque la précision de conception de niveau Pro n’est pas nécessaire.

Pour une présentation non technique, consultez les fonctionnalités et tarifs de Seedream 5.0 Pro. Vous pouvez également tester visuellement la charge utile API sur la page du modèle Seedream 5.0 Pro.

Questions fréquentes

Quel est l’endpoint API de Seedream 5.0 Pro ?

Envoyez les tâches de génération et de modification vers POST https://api.poyo.ai/api/generate/submit.

Quel est l’identifiant du modèle d’édition ?

Utilisez seedream-5.0-pro-edit et incluez une ou plusieurs valeurs dans input.image_urls.

Combien d’images de référence sont prises en charge ?

La documentation actuelle de Poyo.ai prend en charge jusqu’à 10 images de référence pour l’édition avec Seedream 5.0 Pro.

Combien coûte une image via l’API ?

Le tarif actuel de Poyo.ai est de 15 crédits, soit environ $0.075, pour chaque image générée ou modifiée.