API d'édition Seedream v4.5 : édition d'images par programmation

L'utilisation de Seedream v4.5 Edit via l'interface Arteza convient pour des retouches ponctuelles et de petits lots. Pour les workflows à fort volume, comme les catalogues de milliers de SKU, la génération d'images dynamique par utilisateur ou les pipelines d'assets pilotés par un CMS, l'accès API est indispensable. Ce guide présente la structure des endpoints, les paramètres de requête, la gestion des réponses et les bonnes pratiques de production pour créer des systèmes automatisés de retouche d'images avec Seedream v4.5.

En résumé

• Seedream v4.5 Edit est disponible via l'endpoint fal-ai/bytedance/seedream/v4.5/edit
• Même tarif de 1 crédit ($0,10) par image qu'en interface
• Accepte jusqu'à 10 URL d'images en entrée plus un prompt textuel
• Sortie 4 MP (2048×2048) renvoyée sous forme d'URL d'image
• Temps de génération habituel de 30 à 60 secondes : privilégiez les patterns asynchrones en production

Pourquoi utiliser l'API

L'API ouvre des possibilités d'automatisation que l'interface ne peut pas offrir :

• Traitement en lots à grand volume. Traitez 1 000 retouches ou plus en un seul pipeline.
• Génération dynamique. Créez des images à la demande à partir de données utilisateur ou d'enregistrements en base.
• Workflows planifiés. Mises à jour nocturnes de catalogues, régénération déclenchée par des événements.
• Intégration avec vos stacks existants. Node.js, Python, Go, Ruby : n'importe quel client HTTP.
• Production reproductible. Scripts versionnés plutôt que clics manuels.

Si votre cas d'usage implique plus de 20 à 50 retouches similaires, la mise en place de l'API en vaut la peine.

Structure de l'endpoint

Le modèle Seedream v4.5 Edit est disponible à l'adresse suivante :

fal-ai/bytedance/seedream/v4.5/edit

Il s'agit d'un endpoint de modèle fal.ai standard qui peut être appelé directement ou via le système de crédits Arteza.

Authentification

Les requêtes à l'API Arteza s'authentifient via une clé API transmise dans l'en-tête Authorization en tant que token Bearer.

Obtenir votre clé API

1. Connectez-vous sur arteza.ai
2. Accédez aux paramètres de votre compte
3. Trouvez la section API
4. Générez une nouvelle clé API
5. Conservez-la en lieu sûr : traitez-la comme un mot de passe

Ne commitez jamais votre clé API dans le contrôle de source. Utilisez des variables d'environnement :

export SEEDANCE_API_KEY="your_api_key_here"

En-tête d'authentification

Authorization: Bearer your_api_key_here

Structure de la requête

Une requête Seedream v4.5 Edit de base ressemble à ceci :

{
  "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly. Add a subtle contact shadow.",
  "image_urls": [
    "https://your-bucket.com/product-shot.jpg"
  ],
  "num_images": 1,
  "output_format": "png"
}

Référence des paramètres

Jusqu'à 10 URL d'images peuvent être transmises. Le modèle traite la première image comme principale et les suivantes comme références.

Exemple de requête : Node.js

const response = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SEEDANCE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
    image_urls: [
      "https://your-bucket.com/product-shot.jpg"
    ],
    num_images: 1,
    output_format: "png"
  })
});

const result = await response.json();
console.log(result.images[0].url);

Exemple de requête : Python

import os
import requests

response = requests.post(
    "https://api.arteza.ai/v1/seedream/v4.5/edit",
    headers={
        "Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "Replace the background with a polished marble surface. Preserve the product position, color, and lighting exactly.",
        "image_urls": [
            "https://your-bucket.com/product-shot.jpg"
        ],
        "num_images": 1,
        "output_format": "png"
    }
)

result = response.json()
print(result["images"][0]["url"])

Structure de la réponse

Une réponse réussie contient les URL des images générées :

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

Téléchargez l'image depuis l'URL renvoyée : les URL de sortie sont valables pendant 24 heures.

Pattern de génération asynchrone

Seedream v4.5 Edit prend 30 à 60 secondes par requête. En production, il est préférable d'utiliser la génération asynchrone avec des webhooks ou du polling plutôt que des requêtes bloquantes.

Asynchrone basé sur les webhooks

Transmettez un webhook_url dans votre requête et Arteza enverra le résultat en POST dès que la génération sera terminée :

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

Votre gestionnaire de webhook reçoit :

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

La gestion par webhook est le pattern de production recommandé.

Commencez à construire. Essayez l'outil d'abord.

Asynchrone basé sur le polling

Si votre infrastructure ne peut pas recevoir de webhooks, interrogez le statut par polling :

const initResponse = await fetch("https://api.arteza.ai/v1/seedream/v4.5/edit", {
  method: "POST",
  headers: { "Authorization": `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, image_urls, async: true })
});

const { request_id } = await initResponse.json();

// Interrogation jusqu'à la fin
let result;
while (!result) {
  await new Promise(r => setTimeout(r, 5000));
  const statusResponse = await fetch(
    `https://api.arteza.ai/v1/requests/${request_id}`,
    { headers: { "Authorization": `Bearer ${key}` } }
  );
  const status = await statusResponse.json();
  if (status.status === "completed") result = status;
}

Interrogez toutes les 5 à 10 secondes. L'attente totale est généralement de 30 à 60 secondes.

Patterns de production

Pattern 1 : génération en lot pour un catalogue

Exécutez l'API sur votre catalogue produit pour générer des remplacements de fond cohérents pour chaque SKU :

for product in catalog:
    response = requests.post(
        API_URL,
        headers=HEADERS,
        json={
            "prompt": PROMPT_TEMPLATE.format(product_name=product.name),
            "image_urls": [product.source_image_url],
            "webhook_url": WEBHOOK_URL
        }
    )
    log_request(product.id, response.json()["request_id"])

Associez ce code à un gestionnaire de webhook qui enregistre les sorties sur votre CDN et met à jour la fiche produit.

Pattern 2 : retouches utilisateur à la demande

Permettez aux utilisateurs de télécharger des images et d'obtenir des résultats retouchés par l'IA à la demande :

1. L'utilisateur télécharge une image dans votre bucket
2. Votre backend appelle Seedream v4.5 Edit avec un prompt choisi par l'utilisateur
3. Interrogez ou attendez le webhook
4. Renvoyez l'URL du résultat au client de l'utilisateur

Prévoyez environ 60 secondes d'attente par retouche dans votre UX.

Pattern 3 : pipeline d'assets piloté par un CMS

Lorsque du contenu est publié dans votre CMS, générez automatiquement les images associées :

1. Le CMS émet un événement de publication
2. Une fonction serverless se déclenche
3. Elle appelle Seedream v4.5 Edit avec un prompt modèle
4. Elle stocke le résultat sur le CDN
5. Elle met à jour l'enregistrement CMS avec l'URL de l'image

Ce pattern élimine la création manuelle d'images pour les publications à fort volume.

Gestion des erreurs

Réponses d'erreur courantes :

Encapsulez toujours les appels API dans un bloc try/except avec une logique de réessai pour les réponses 429 et 500.

Limites de taux

Arteza applique des limites de taux raisonnables sur l'API. Pour la plupart des workflows de production vous ne les atteindrez pas, mais pour des lots massifs de 1 000 requêtes ou plus, mettez en place :

• Un backoff exponentiel sur les réponses 429
• Des limites de requêtes simultanées (commencez à 5 en parallèle, ajustez à la hausse)
• Une file d'attente de requêtes pour un débit prévisible

Contactez le support pour des limites de taux plus élevées sur des charges de production intensives.

Coût à l'échelle de l'API

Les appels API coûtent autant que les appels via l'interface : 1 crédit ($0,10) par image. Pour planifier votre budget :

• 100 appels API = 100 crédits (largement dans le plan Starter à 5 dollars)
• 1 000 appels API = 1 000 crédits (le plan Studio à 120 dollars, 1 800 par mois)
• 10 000 appels API = 10 000 crédits (le plan Studio à 120 dollars plus environ 8 200 crédits en recharge)

Pour des volumes supérieurs à 10 000 par mois, contactez l'équipe pour un tarif personnalisé.

Bonnes pratiques

1. Utilisez les webhooks en production. Le polling fonctionne mais gaspille des ressources.
2. Stockez vos prompts dans le contrôle de version. Traitez les prompts comme du code.
3. Journalisez tout. Identifiants de requête, prompts, sorties, erreurs.
4. Validez les entrées avant d'appeler l'API. Les URL d'images incorrectes gaspillent des crédits.
5. Surveillez le solde de crédits. Déclenchez une alerte quand vous passez sous un seuil.
6. Testez les changements de prompt en staging. Validez sur 3 à 5 images avant de lancer un lot complet.
7. Mettez en cache les résultats. Si les entrées sont identiques, réutilisez les sorties précédentes.

Pour aller plus loin

• Guide complet de modification Seedream v4.5
• Tutoriel de modification par lot
• Détail des tarifs

Démarrer

Générez votre clé API dans le tableau de bord Arteza, récupérez 10 crédits gratuits et exécutez l'exemple Node.js ci-dessus avec une photo produit. L'API libère tout le potentiel de production de Seedream v4.5 Edit : une fois intégrée, tout le reste relève de l'ingénierie de prompt. Pour commencer par des tests pratiques, ouvrir l'outil web et validez vos prompts avant d'automatiser.