Clave API de Seedream: acceso gratis, playground y ejemplo en Node.js

Escribir Seedream API Key en un buscador te lleva a dos lugares muy distintos: la plataforma propia de ByteDance y un montón de sitios que alojan el modelo por ti. Cuál necesitas depende de lo que quieras lanzar. Si solo quieres ver lo que genera Seedream, no necesitas ninguna credencial. Si quieres un script que envíe prompts y guarde archivos, necesitas una cuenta con un proveedor de API, y los proveedores difieren mucho en precio, límites y acceso a los modelos. Este artículo explica cada ruta con datos verificados en las páginas oficiales, señala dónde termina el acceso gratis e incluye un script de Node.js que puedes ejecutar hoy. Un resultado que conviene dejar claro desde el principio: la API de PicassoIA sirve sus cuatro modelos propios, y Seedream no es uno de ellos, así que el playground es donde vive Seedream en PicassoIA.

Dos rutas hacia Seedream

Seedream es una familia de modelos de imagen de ByteDance, y el mismo nombre de modelo aparece detrás de puertas muy distintas. Antes de copiar cualquier código, elige la puerta que coincida con tu objetivo.

Una regla práctica: si el resultado son unas cuantas imágenes para una publicación o una propuesta, usa el playground y quédate ahí. Si estás construyendo un producto cuyos usuarios activan Seedream directamente, ve al proveedor y presupuesta la facturación de pago por uso desde el primer día. Si automatizas lotes de miniaturas o ediciones con modelos de PicassoIA, la API de PicassoIA encaja, siempre que tu plan lo permita. Combinar rutas es lo normal: haz borradores en el playground y luego pasa el prompt ganador a un script.

La ruta del playground

La forma más rápida de empezar es el navegador. Seedream 5 Pro convierte un prompt de texto, o hasta 10 fotos de referencia, en una imagen de 1K o 2K. Seedream 4.5 lleva la resolución más lejos, con salida en 2K y 4K de hasta 4096 píxeles y un modo por lotes que devuelve hasta 15 imágenes relacionadas en una sola ejecución. Las dos páginas de modelo describen la experiencia en el navegador como gratuita y en línea, sin necesidad de programar.

Esta ruta sirve a quien itera a ojo: cambia una frase sobre la iluminación, regenera y compara los dos resultados lado a lado. No sirve para un trabajo que necesite 500 imágenes de la noche a la mañana, porque cada generación es un clic manual.

La ruta del proveedor directo

La propia página de Seedream 5 Pro cita la guía de BytePlus y señala que los prompts funcionan mejor con menos de 600 palabras en inglés. BytePlus gestiona ModelArk, su plataforma de modelos, y de esa consola sale una credencial directa de Seedream. Según la documentación de ModelArk, las cuentas nuevas reciben una cuota de prueba gratuita de inferencia que compensa las tarifas de inferencia de pago por uso. Esa cuota se calcula por separado para cada modelo y se comparte bajo la cuenta principal. La generación de imágenes pasa por la API de generación de imágenes, que expone un endpoint /images/generations. Los documentos de integración de terceros indican https://ark.ap-southeast.bytepluses.com/api/v3 como URL base regional predeterminada.

💡 Copia el ID exacto del modelo o del endpoint desde tu consola de ModelArk, no desde un blog, este incluido. Los identificadores cambian con cada versión, y un ID desactualizado hace fallar la petición antes de que llegue al modelo.

No incluyo a propósito un ejemplo de código para el proveedor directo. La forma de la petición y los IDs de modelo pertenecen a BytePlus, cambian, y una suposición errónea te hace perder la tarde. El ejemplo de Node.js más adelante en este artículo usa la API de PicassoIA, donde cada endpoint y cada campo de abajo proviene directamente de su documentación.

Acceso gratis sin ninguna credencial

El acceso gratis es real, pero tiene límites. Esto es lo que afirma cada página y dónde terminan esas afirmaciones.

Lo que ofrecen las páginas de los modelos

Lo que no significa gratis

Que algo sea gratis en el navegador no dice nada sobre la API. La página de PicassoIA Image anuncia generación ilimitada de texto a imagen, sin tope por imagen. La documentación de la API indica que las predicciones son actualmente gratuitas y no consumen créditos, pero esa misma documentación exige el plan Infinite, y una petición sin él devuelve 403 plan_required.

La página de precios incluye el acceso a la API en más de un nivel, así que dos páginas lo formulan de forma distinta. Revisa tu propio plan antes de construir un producto sobre él. Lo mismo vale para las cuotas de prueba de los proveedores: una prueba es un saldo inicial, no una asignación permanente.

Los límites también pueden aplicarse a la resolución, al tamaño del lote o a la concurrencia, en lugar de a un recuento fijo de imágenes. Lee la tabla de límites en la sección de la API antes de diseñar un trabajo por lotes en torno a una cifra que solo has visto en una página de aterrizaje.

Cómo usar Seedream 5 Pro

Seedream 5 Pro en PicassoIA es rápido de configurar. Sigue estos pasos en orden:

1. Abre la página del modelo. Ve a Seedream 5 Pro e inicia sesión.
2. Escribe el prompt. El límite es de 4000 caracteres, pero BytePlus recomienda quedarse por debajo de 600 palabras en inglés.
3. Elige un tamaño. 1K equivale a unos 2 megapíxeles y 2K a unos 4 megapíxeles. El predeterminado es 2K.
4. Elige una relación de aspecto. Las opciones son 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 y 21:9. La predeterminada, match_input_image, copia la relación de tu primera foto de referencia.
5. Añade referencias si las tienes. Incluye de 1 a 10 imágenes para mezclar rostros, objetos o estilos en un solo resultado.
6. Define el formato de salida y genera. Elige PNG o JPEG, ejecútalo y descarga el archivo.

Ajustes del prompt que importan

Tres ajustes cambian los resultados más que cualquier adjetivo del prompt:

• Tamaño. Usa 1K para los borradores y 2K para todo lo que vayas a publicar. Cambia a Seedream 4.5 cuando necesites 4K, porque Seedream 5 Pro llega como máximo a 2K.
• Número de referencias. Más referencias aportan coherencia, pero también más restricciones. Empieza con dos o tres y añade más solo cuando el rostro o el producto se desvíen.
• Relación de aspecto. Define una explícitamente cuando la imagen tenga un destino. Dejar que coincida con una referencia es cómodo, pero hereda en silencio el encuadre de esa foto.

💡 Describe la luz, no el ambiente. "Sol bajo desde la izquierda, sombras largas sobre el pavimento" le da al modelo algo que dibujar. "Atmósfera dramática" no le da nada.

Este es un prompt que usa bien estos ajustes, escrito para 2K a 16:9: Un bol de cerámica con naranjas sobre un paño de lino junto a una ventana, sol bajo de la mañana desde la izquierda, sombras suaves que se extienden sobre la mesa de madera, aspecto de lente de 85 mm, profundidad de campo reducida, tejido del lino visible. Nombra un sujeto, una dirección de la luz y una textura de superficie en menos de 50 palabras. Seedream 5 Pro acepta mucho más, pero un prompt corto y concreto es la mejor base: añade un detalle por ejecución y conserva el cambio solo si la imagen mejora.

La ruta de la API de PicassoIA

De dónde sale la credencial

La API para desarrolladores de PicassoIA se autentica con un secreto Bearer que empieza por pia_sk_. Lo creas desde tu cuenta en la página de la API de PicassoIA, y cada cuenta puede tener dos. Trátalo como una contraseña: guárdalo en una variable de entorno, nunca en un repositorio, y rótalo si alguna vez aparece en una captura de pantalla o en un registro.

En Node 20.6 o posterior puedes guardar el secreto en un archivo .env y cargarlo con node --env-file=.env generate.mjs, de modo que nunca quede en el historial de tu terminal. Añade .env a .gitignore antes del primer commit. Si despliegas el script, define la variable en el gestor de secretos de tu host en lugar de copiar el archivo.

Modelos que sirve la API

La documentación de la API enumera cuatro modelos:

• PicassoIA Image, slug picassoia/picassoia-image, para texto a imagen
• PicassoIA Image Editor Pro, slug picassoia/picassoia-image-editor-pro, para editar con 1 a 4 imágenes de entrada
• PicassoIA Video, slug picassoia/picassoia-video
• Seedance 2.5 Lite, slug picassoia/seedance-2.5-lite, video con audio

Seedream no está en esa lista. Si un tutorial te dice que llames a un modelo de Seedream con un secreto pia_sk_, revisa antes la lista de modelos de tu cuenta.

Plan y límites

Ejemplo de Node.js que funciona

Necesitas Node 18 o posterior, que incluye un fetch global. Guarda el código como generate.mjs, exporta tu secreto como PICASSOIA_SECRET y ejecuta node generate.mjs.

La función auxiliar

Esta función auxiliar sigue la documentación oficial, con un cambio: la variable de entorno se llama PICASSOIA_SECRET. Crea una predicción, espera el intervalo que sugiere la API, consulta el estado hasta que el trabajo llega a un estado final y devuelve la salida.

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
}

Copiar prompt

Genera tu primera imagen

Añade esto al mismo archivo. Pide a PicassoIA Image una JPEG de 16:9 y la guarda en disco.

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)

Copiar prompt

La línea [].concat(output) acepta una única URL o una lista, así que el script sigue funcionando sea cual sea la forma de la salida.

Edita una foto existente

PicassoIA Image Editor Pro necesita un prompt y de 1 a 4 imágenes. La documentación indica data URL de hasta 5 MB cada una, así que lee el archivo y codifícalo:

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)

Copiar prompt

Errores y límites en la práctica

Lee el cuerpo del error

Cuando la creación falla, la función auxiliar lanza el code y el detail propios de la API, por eso un plan que falta aparece como plan_required y no como un vago error de red. Después de la creación, una predicción pasa por cinco estados:

Una predicción fallida no se reinicia sola, así que reintentar significa crear una nueva. Un envoltorio sencillo gestiona los fallos transitorios y se rinde de inmediato ante un error de plan, que ninguna espera va a arreglar:

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)
    }
  }
}

Copiar prompt

Mantente por debajo de cinco predicciones

El límite es de cinco predicciones simultáneas por cuenta, y el recuento se comparte entre todas las credenciales y todas las generaciones MCP. Un script por lotes y una sesión de chat abierta usan el mismo grupo de cinco. Un pequeño grupo de workers te mantiene por debajo del tope y deja una plaza 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' })),
)

Copiar prompt

Añade un LLM y movimiento

Una imagen rara vez es el último paso. Dos colecciones más de PicassoIA encajan directamente en el flujo: los modelos de lenguaje (LLM) antes de la imagen, y el video después.

Redacta prompts con un LLM

Una idea de una sola línea da poco material al modelo. Pégala en Claude Sonnet 5 o en Gemini 3.5 Flash y pide que le dé estructura:

Reescribe esta idea como un prompt de imagen de unas 120 palabras con el sujeto, el escenario, la dirección de la luz, la lente y la textura de la superficie: "pescador remendando redes al amanecer".

Envía el resultado a Seedream 5 Pro en el playground o a PicassoIA Image mediante el script de arriba. Los cuatro modelos de la API que aparecen antes no incluyen un modelo de chat, así que este paso se hace en el sitio.

Anima los resultados

Una vez que una imagen fija te convence, Seedance 2.5 Lite puede usarla como fotograma inicial. Su página indica clips de 5 o 10 segundos a 480p o 720p, con audio sincronizado, y describe generación ilimitada para los miembros de Wonder. PicassoIA Video acepta la misma entrada de imagen a video con 5 segundos fijos a 24 fotogramas por segundo. Para estilos estilizados, PicassoIA también ofrece una categoría de efectos con cientos de efectos de video, a la que llegas desde la página de todos los modelos.

Describe el movimiento en orden, como lo haría un director: El pescador tira de la red hacia sí, la cámara se desplaza lentamente a la derecha, las gaviotas cruzan el cielo pálido, la luz suave se mantiene estable. Una acción del sujeto, un movimiento de cámara y una nota de iluminación bastan para un clip corto.

Ejecuta tu primer prompt de Seedream

Elige una idea, de una sola frase, y conviértela en una imagen hoy. Abre Seedream 5 Pro en PicassoIA, pega un prompt, elige 2K y 16:9, y genera. Ejecuta el mismo prompt en Seedream 4.5 a 4K y compara los dos archivos a tamaño completo.

Cuando hacer clic deje de ser práctico, crea una credencial de la API de PicassoIA, pega la función auxiliar de arriba en un archivo y envía tus prompts a través de PicassoIA Image. Cambia una variable por ejecución, conserva las semillas que te gusten y deja que el límite de cinco plazas marque tu ritmo. Cada modelo mencionado aquí está a un clic en la página de todos los modelos.