Clé API Seedream : accès gratuit, playground et exemple Node.js

Taper Seedream API Key dans une barre de recherche vous mène vers deux endroits très différents : la plateforme de ByteDance elle-même, et une foule de sites qui hébergent le modèle pour vous. Lequel vous faut-il dépend de ce que vous comptez livrer. Si vous voulez seulement voir ce que produit Seedream, vous n’avez besoin d’aucun identifiant. Si vous voulez un script qui envoie des prompts et enregistre des fichiers, il vous faut un compte chez un fournisseur d’API, et les fournisseurs diffèrent beaucoup en prix, en limites et en accès aux modèles. Cet article présente chaque voie en s’appuyant sur des informations vérifiées sur les pages officielles, indique où l’accès gratuit s’arrête et propose un script Node.js que vous pouvez exécuter dès aujourd’hui. Un résultat à énoncer d’emblée : l’API PicassoIA sert ses quatre propres modèles, et Seedream n’en fait pas partie ; le playground est donc l’endroit où Seedream se trouve sur PicassoIA.

Deux voies vers Seedream

Seedream est une famille de modèles d’images de ByteDance, et le même nom de modèle apparaît derrière des portes très différentes. Avant de copier le moindre code, choisissez la porte qui correspond à votre objectif.

Une règle simple : si le résultat se limite à quelques images pour un post ou une présentation, utilisez le playground et arrêtez-vous là. Si vous développez un produit dont les utilisateurs déclenchent Seedream directement, passez par le fournisseur et prévoyez dès le départ une facturation à l’usage. Si vous automatisez des lots de vignettes ou de retouches avec les modèles PicassoIA, l’API PicassoIA convient, à condition que votre offre le permette. Combiner les voies est tout à fait normal : esquissez dans le playground, puis reprenez le prompt gagnant dans un script.

La voie playground

Le moyen le plus rapide pour commencer passe par le navigateur. Seedream 5 Pro transforme un prompt texte, ou jusqu’à 10 photos de référence, en une image 1K ou 2K. Seedream 4.5 pousse la résolution plus loin, avec une sortie en 2K et 4K jusqu’à 4096 pixels et un mode lot qui renvoie jusqu’à 15 images liées en une seule exécution. Les deux pages de modèles décrivent l’expérience navigateur comme gratuite et en ligne, sans besoin de coder.

Cette voie convient à quiconque itère à l’œil : modifier une formule d’éclairage, relancer la génération, comparer les deux résultats côte à côte. Elle ne convient pas à un travail qui exige 500 images pendant la nuit, car chaque génération demande un clic manuel.

La voie du fournisseur direct

La page Seedream 5 Pro elle-même cite les recommandations de BytePlus, en précisant que les prompts fonctionnent mieux en dessous de 600 mots en anglais. BytePlus exploite ModelArk, sa plateforme de modèles, et c’est cette console qui délivre un identifiant Seedream direct. Selon la documentation de ModelArk, les nouveaux comptes reçoivent un quota d’essai gratuit d’inférence qui compense les frais d’inférence à l’usage. Ce quota est calculé séparément pour chaque modèle et partagé sous le compte principal. La génération d’images passe par l’API de génération d’images, qui expose un point de terminaison /images/generations. Les documentations d’intégration tierces indiquent https://ark.ap-southeast.bytepluses.com/api/v3 comme URL de base régionale par défaut.

💡 Copiez l’identifiant exact du modèle ou du point de terminaison depuis votre console ModelArk, pas depuis un article de blog, celui-ci compris. Les identifiants changent à chaque version, et un identifiant périmé fait échouer la requête avant qu’elle n’atteigne le modèle.

Je ne donne volontairement aucun exemple de code pour le fournisseur direct. La forme des requêtes et les identifiants de modèles appartiennent à BytePlus, ils changent, et une supposition erronée vous fera perdre votre après-midi. L’exemple Node.js plus loin dans cet article utilise l’API PicassoIA, où chaque point de terminaison et chaque champ ci-dessous proviennent directement de sa documentation.

Accès gratuit sans aucun identifiant

L’accès gratuit est réel, mais il a des limites. Voici ce que promet chaque page et où s’arrêtent ces promesses.

Ce qu’offrent les pages des modèles

Ce que gratuit ne veut pas dire

Être gratuit dans le navigateur ne dit rien de l’API. La page PicassoIA Image annonce une génération texte vers image illimitée, sans plafond par image. La documentation de l’API indique que les prédictions sont actuellement gratuites et ne consomment aucun crédit, mais cette même documentation exige l’offre Infinite, et une requête sans celle-ci renvoie 403 plan_required.

La page des tarifs indique l’accès à l’API sur plusieurs niveaux, donc deux pages formulent cela différemment. Vérifiez votre propre offre avant de bâtir un produit dessus. La même prudence s’applique aux quotas d’essai des fournisseurs : un essai est un solde de départ, pas une allocation permanente.

Les limites peuvent aussi porter sur la résolution, la taille des lots ou la simultanéité plutôt que sur un nombre fixe d’images. Lisez le tableau des limites dans la section API avant de concevoir une tâche par lots autour d’un chiffre que vous n’avez vu que sur une page d’accueil.

Comment utiliser Seedream 5 Pro

Seedream 5 Pro sur PicassoIA se configure rapidement. Suivez ces étapes dans l’ordre :

1. Ouvrez la page du modèle. Rendez-vous sur Seedream 5 Pro et connectez-vous.
2. Rédigez le prompt. La limite est de 4000 caractères, mais BytePlus recommande de rester sous 600 mots en anglais.
3. Choisissez une taille. 1K correspond à environ 2 mégapixels et 2K à environ 4 mégapixels. La valeur par défaut est 2K.
4. Sélectionnez un format. Les options sont 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 et 21:9. La valeur par défaut, match_input_image, reprend le format de votre première photo de référence.
5. Ajoutez des références si vous en avez. Ajoutez 1 à 10 images pour fondre des visages, des objets ou des styles dans un seul résultat.
6. Réglez le format de sortie et générez. Choisissez PNG ou JPEG, lancez la génération et téléchargez le fichier.

Les réglages du prompt qui comptent

Trois réglages modifient les résultats plus que n’importe quel adjectif du prompt :

• Taille. Utilisez 1K pour les brouillons et 2K pour tout ce que vous publierez. Passez sur Seedream 4.5 quand vous avez besoin de 4K, car Seedream 5 Pro plafonne à 2K.
• Nombre de références. Davantage de références apportent de la cohérence, mais aussi des contraintes. Commencez avec deux ou trois, et n’en ajoutez que lorsque le visage ou le produit dérive.
• Format. Définissez-le explicitement lorsque l’image a une destination. Le laisser reprendre celui d’une référence est pratique, mais cela hérite silencieusement du recadrage de cette photo.

💡 Décrivez la lumière, pas l’ambiance. « Soleil bas à gauche, longues ombres sur le pavé » donne au modèle quelque chose à dessiner. « Atmosphère dramatique » ne lui donne rien.

Voici un prompt qui exploite bien ces réglages, rédigé pour 2K en 16:9 : A ceramic bowl of oranges on a linen cloth beside a window, low morning sun from the left, soft shadows stretching across the wooden table, 85mm lens look, shallow depth of field, visible weave in the linen. Il nomme un sujet, une direction de lumière et une texture de surface en moins de 50 mots. Seedream 5 Pro accepte bien davantage, mais un prompt court et concret reste la meilleure base : ajoutez un détail à chaque exécution et ne gardez la modification que si l’image s’améliore.

La voie de l’API PicassoIA

D’où vient l’identifiant

L’API développeur PicassoIA authentifie avec un secret Bearer qui commence par pia_sk_. Vous le créez depuis votre compte via la page de l’API PicassoIA, et chaque compte peut en détenir deux. Traitez-le comme un mot de passe : conservez-le dans une variable d’environnement, jamais dans un dépôt, et renouvelez-le s’il fuite dans une capture d’écran ou un journal.

Sous Node 20.6 ou plus récent, vous pouvez garder le secret dans un fichier .env et le charger avec node --env-file=.env generate.mjs, afin qu’il n’atterrisse jamais dans l’historique de votre shell. Ajoutez .env à .gitignore avant le premier commit. Si vous déployez le script, définissez la variable dans le gestionnaire de secrets de votre hébergeur plutôt que de copier le fichier.

Les modèles servis par l’API

La documentation de l’API liste quatre modèles :

• PicassoIA Image, slug picassoia/picassoia-image, pour la génération texte vers image
• PicassoIA Image Editor Pro, slug picassoia/picassoia-image-editor-pro, pour la retouche à partir de 1 à 4 images d’entrée
• PicassoIA Video, slug picassoia/picassoia-video
• Seedance 2.5 Lite, slug picassoia/seedance-2.5-lite, vidéo avec audio

Seedream ne figure pas dans cette liste. Si un tutoriel vous demande d’appeler un modèle Seedream avec un secret pia_sk_, vérifiez d’abord la liste des modèles dans votre propre compte.

Offre et limites

Exemple Node.js qui fonctionne

Il vous faut Node 18 ou plus récent, qui fournit un fetch global. Enregistrez le code sous generate.mjs, exportez votre secret sous PICASSOIA_SECRET, puis lancez node generate.mjs.

La fonction utilitaire

Cette fonction utilitaire suit la documentation officielle, avec une seule modification : la variable d’environnement s’appelle PICASSOIA_SECRET. Elle crée une prédiction, attend l’intervalle suggéré par l’API, interroge jusqu’à ce que la tâche atteigne un statut final, et renvoie le résultat.

const API = 'https://api.picassoia.com/v1'
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_SECRET}`,
  'Content-Type': 'application/json',
}
const sleep = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000))

async function run(model, input) {
  const created = await fetch(`${API}/models/${model}/predictions`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ input }),
  })
  let prediction = await created.json()
  if (!created.ok) throw new Error(`${prediction.code}: ${prediction.detail}`)

  while (!['succeeded', 'failed', 'canceled'].includes(prediction.status)) {
    await sleep(prediction.eta?.next_poll_in_seconds ?? 2)
    prediction = await (await fetch(prediction.urls.get, { headers })).json()
  }
  if (prediction.status !== 'succeeded') throw new Error(prediction.error ?? prediction.status)
  return prediction.output
}

Copier le prompt

Générer votre première image

Ajoutez ceci au même fichier. Il demande à PicassoIA Image un JPEG 16:9 unique et l’écrit sur le disque.

import { writeFile } from 'node:fs/promises'

const output = await run('picassoia/picassoia-image', {
  prompt: 'A weathered fisherman mending a net on a grey pier at dawn, 35mm film look, soft side light',
  aspect_ratio: '16:9',
  num_outputs: 1,
  output_format: 'jpg',
  output_quality: 80,
})

const [url] = [].concat(output)
const image = await fetch(url)
await writeFile('result.jpg', Buffer.from(await image.arrayBuffer()))
console.log('Saved result.jpg from', url)

Copier le prompt

La ligne [].concat(output) accepte soit une URL unique, soit une liste, si bien que le script continue de fonctionner quelle que soit la forme du résultat.

Retoucher une photo existante

PicassoIA Image Editor Pro demande un prompt et de 1 à 4 images. La documentation liste des data URL de 5 Mo maximum chacune : lisez donc le fichier et encodez-le :

import { readFile } from 'node:fs/promises'

const photo = await readFile('portrait.jpg')
const edited = await run('picassoia/picassoia-image-editor-pro', {
  prompt: 'Replace the grey wall with warm red brick, keep the lighting and the face unchanged',
  images: [`data:image/jpeg;base64,${photo.toString('base64')}`],
  aspect_ratio: 'match_input_image',
})
console.log(edited)

Copier le prompt

Erreurs et limites en pratique

Lire le corps de l’erreur

Lorsque la création échoue, la fonction utilitaire lève l’code et le detail propres à l’API, ce qui explique pourquoi une offre manquante apparaît comme plan_required au lieu d’une vague erreur réseau. Après la création, une prédiction passe par cinq statuts :

Une prédiction échouée ne redémarre pas toute seule : une nouvelle tentative implique donc de créer une nouvelle prédiction. Un fin wrapper gère les échecs transitoires et abandonne immédiatement en cas d’erreur d’offre, que l’attente ne réglera jamais :

async function runWithRetry(model, input, attempts = 3) {
  for (let i = 1; i <= attempts; i++) {
    try {
      return await run(model, input)
    } catch (error) {
      if (i === attempts || String(error.message).startsWith('plan_required')) throw error
      await sleep(i * 5)
    }
  }
}

Copier le prompt

Rester sous cinq prédictions

La limite est de cinq prédictions simultanées par compte, et ce décompte est partagé entre tous les identifiants et toutes les générations MCP. Un script par lots et une session de chat ouverte puisent dans le même réservoir de cinq. Un petit pool de workers vous maintient sous le plafond et laisse un emplacement libre :

async function pool(tasks, limit = 4) {
  const results = []
  let next = 0
  const worker = async () => {
    while (next < tasks.length) {
      const i = next++
      results[i] = await tasks[i]()
    }
  }
  await Promise.all(Array.from({ length: limit }, worker))
  return results
}

const prompts = ['a red bicycle against a pale wall', 'a lighthouse on a grey coast']
const images = await pool(
  prompts.map((prompt) => () => run('picassoia/picassoia-image', { prompt, aspect_ratio: '16:9' })),
)

Copier le prompt

Ajouter un LLM et le mouvement

Une image n’est que rarement la dernière étape. Deux autres collections de PicassoIA s’intègrent directement dans le flux : les grands modèles de langage avant l’image, et la vidéo après.

Rédiger des prompts avec un LLM

Une idée d’une seule ligne donne peu de matière au modèle. Collez-la dans Claude Sonnet 5 ou Gemini 3.5 Flash et demandez une structure :

Réécrivez cette idée sous la forme d’un seul prompt d’image d’environ 120 mots, avec le sujet, le décor, la direction de la lumière, l’objectif et la texture des surfaces : « pêcheur raccommodant ses filets à l’aube ».

Envoyez le résultat à Seedream 5 Pro dans le playground, ou à PicassoIA Image via le script ci-dessus. Les quatre modèles d’API listés plus haut ne comprennent pas de modèle de chat, cette étape se déroule donc sur le site.

Animer les résultats

Une fois qu’une image fixe vous plaît, Seedance 2.5 Lite peut l’utiliser comme première image. Sa page liste des clips de 5 ou 10 secondes en 480p ou 720p, avec un son synchronisé, et décrit une génération illimitée pour les membres Wonder. PicassoIA Video accepte la même entrée image vers vidéo, avec une durée fixe de 5 secondes et une fréquence d’images de 24 fps. Pour les rendus stylisés, PicassoIA propose aussi une catégorie d’effets avec des centaines d’effets vidéo, accessible depuis la page de tous les modèles.

Décrivez le mouvement dans l’ordre, comme le ferait un réalisateur : The fisherman pulls the net toward him, the camera drifts slowly to the right, gulls cross the pale sky, the soft light holds steady. Une action du sujet, un mouvement de caméra et une indication de lumière suffisent pour un court clip.

Lancez votre premier prompt Seedream

Choisissez une idée, une seule phrase, et transformez-la en image dès aujourd’hui. Ouvrez Seedream 5 Pro sur PicassoIA, collez un prompt, choisissez 2K et 16:9, puis générez. Lancez le même prompt sur Seedream 4.5 en 4K et comparez les deux fichiers en taille réelle.

Quand cliquer ne sera plus pratique, créez un identifiant API PicassoIA, collez la fonction utilitaire ci-dessus dans un fichier et envoyez vos prompts via PicassoIA Image. Changez une variable à chaque exécution, conservez les seeds qui vous plaisent, et laissez la limite de cinq emplacements dicter votre rythme. Chaque modèle mentionné ici est à un clic sur la page de tous les modèles.