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

L'utilisation de Seedream v4.5 Edit via l'interface Arteza fonctionne bien pour les modifications ponctuelles et les petits lots. Pour les flux de travail à haut volume - catalogues avec des milliers de SKU, génération d'images dynamiques par utilisateur, pipelines d'actifs pilotés par CMS - vous avez besoin d'un accès API. Ce guide vous montre la structure des points de terminaison, les paramètres de demande, la gestion des réponses et les modèles de production pour construire des systèmes d'édition d'images automatisés sur Seedream v4.5.

Résumé

• Seedream v4.5 Edit est disponible via le point de terminaison fal-ai/bytedance/seedream/v4.5/edit
• Même tarification de 8 crédits ($0.08) par image que l'interface
• Accepte jusqu'à 10 URL d'images source plus une demande texte
• Sortie 4MP (2048×2048) renvoyée sous forme d'URL d'image
• Temps de génération typique de 30 à 60 secondes - utilisez des modèles asynchrones pour la production

Pourquoi utiliser l'API

L'API déverrouille des modèles d'automatisation que l'interface ne peut pas égaler :

• Traitement par lots à haut volume. Traitez 1 000+ modifications en une seule exécution de pipeline.
• Génération dynamique. Construisez des images à la demande à partir de données utilisateur ou d'enregistrements de base de données.
• Flux de travail programmés. Mises à jour de catalogue nocturnes, régénération déclenchée par événement.
• Intégration avec les piles existantes. Node.js, Python, Go, Ruby - tout client HTTP.
• Production reproductible. Scripts contrôlés en version plutôt que des clics manuels.

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

Structure du point de terminaison

Le modèle Seedream v4.5 Edit est disponible à :

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

C'est un point de terminaison de modèle fal.ai standard qui peut être appelé directement ou via le système de crédits Arteza.

Authentification

Les demandes d'API Arteza s'authentifient via une clé API transmise dans l'en-tête Authorization comme jeton Bearer.

Obtenir votre clé API

1. Connectez-vous sur arteza.ai
2. Accédez à vos paramètres de compte
3. Trouvez la section API
4. Générez une nouvelle clé API
5. Stockez-la en toute sécurité - traitez-la comme un mot de passe

Ne validez 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 demande

Une demande de base Seedream v4.5 Edit 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 passées. Le modèle traite la première image comme primaire et les images suivantes comme références.

Exemple de demande : 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 demande : 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 comprend 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 valides pendant 24 heures.

Modèle de génération asynchrone

Seedream v4.5 Edit prend 30 à 60 secondes par demande. Pour la production, vous voudrez probablement une génération asynchrone avec webhooks ou sondage au lieu de demandes bloquantes.

Asynchrone basé sur webhook

Passez une webhook_url dans votre demande et Arteza enverra le résultat par POST quand 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 des webhooks est le modèle de production recommandé.

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

Asynchrone basé sur sondage

Si votre infrastructure ne peut pas recevoir de webhooks, interrogez l'état :

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();

// Poll for completion
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 tous les 5 à 10 secondes. L'attente totale est généralement de 30 à 60 secondes.

Modèles de production

Modèle 1 : Génération par lots de catalogue

Exécutez l'API sur votre catalogue de produits pour générer des changements d'arrière-plan 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-le à un gestionnaire de webhook qui enregistre les sorties sur votre CDN et met à jour l'enregistrement du produit.

Modèle 2 : Modifications utilisateur à la demande

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

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

Budgétisez environ 60 secondes de temps d'attente par modification dans votre UX.

Modèle 3 : Pipeline d'actifs piloté par CMS

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

1. Le CMS émet un événement de publication
2. La fonction sans serveur se déclenche
3. Appelle Seedream v4.5 Edit avec une demande de modèle
4. Stocke le résultat sur CDN
5. Met à jour l'enregistrement CMS avec l'URL de l'image

Ce modèle élimine la création d'images manuelle pour la publication à haut volume.

Gestion des erreurs

Réponses d'erreur courantes :

Enveloppez toujours les appels API dans un try/except avec une logique de nouvelle tentative pour les réponses 429 et 500.

Limites de débit

Arteza applique des limites de débit raisonnables sur l'API. Pour la plupart des flux de travail de production, vous ne les atteindrez pas, mais pour les lots en masse de 1 000+ demandes, mettez en œuvre :

• Backoff exponentiel sur les réponses 429
• Limites de demandes simultanées (commencez à 5 parallèles, ajustez)
• Mise en file d'attente des demandes pour un débit prévisible

Contactez le support pour des limites de débit plus élevées sur les charges de production lourdes.

Coût au volume de l'API

Les appels API coûtent le même que les appels de l'interface : 8 crédits ($0.08) par image. À titre informatif :

• 100 appels API = 800 crédits (niveau Starter, $10)
• 1 000 appels API = 8 000 crédits (niveau Pro, $50)
• 10 000 appels API = 80 000 crédits (plusieurs niveaux Studio, ~$650)

Pour les volumes supérieurs à 10 000/mois, contactez l'équipe pour une tarification personnalisée.

Bonnes pratiques

1. Utilisez les webhooks en production. Le sondage fonctionne mais gaspille des ressources.
2. Stockez les demandes dans le contrôle de version. Traitez les demandes comme du code.
3. Enregistrez tout. ID de demande, demandes, sorties, erreurs.
4. Validez les entrées avant d'appeler. Les mauvaises URL d'images gaspillent les crédits.
5. Surveillez le solde des crédits. Alertez quand vous tombez en dessous d'un seuil.
6. Testez les modifications de demande en staging. Validez sur 3 à 5 images avant d'exécuter un lot complet.
7. Mettez en cache les résultats. Si les entrées sont identiques, réutilisez les sorties précédentes.

Lectures supplémentaires

• Guide complet d'édition Seedream v4.5
• Tutoriel d'édition par lot
• Détails des tarifs

Commencer

Générez votre clé API dans le tableau de bord Arteza, récupérez 50 crédits gratuits et exécutez l'exemple Node.js ci-dessus avec une photo de produit. L'API déverrouille le plein potentiel de production de Seedream v4.5 Edit - une fois que c'est connecté, tout le reste est de l'ingénierie des demandes. Pour tester les mains libres d'abord, ouvrir l'outil web et validez vos demandes avant d'automatiser.