Cómo usar la API de imágenes de Seedream 5.0 Pro

Puedes poner a funcionar Seedream 5.0 Pro con una solicitud POST, una clave de API y un paso de seguimiento: envía el trabajo, obtén un task_id y luego comprueba el estado hasta que la imagen esté lista. Si te saltas ese segundo paso, no obtendrás el archivo final.

Aquí va la versión corta:

• Envío las solicitudes a https://api.apimart.ai/v1/images/generations
• Añado Authorization: Bearer YOUR_API_KEY
• Establezco model en doubao-seedream-5-0-pro
• Incluyo prompt, size y n
• Uso texto a imagen para nuevas ideas de imagen
• Uso imagen a imagen cuando quiero que la salida se mantenga más cerca de una o más imágenes de referencia
• Guardo las URL de las imágenes rápido, porque caducan después de 24 horas
• Uso trabajos asíncronos para salidas lentas como imágenes 3K, que pueden tardar unos 35 a 50 segundos
• Vigilo el coste, ya que el precio ronda los 0,0320 $ por imagen

Lo principal que recordaría: mantén la clave en el servidor, pasa n como número y usa sondeo o un webhook para los trabajos más largos.

Algunos detalles importan más de lo que parece. Por ejemplo, 401 a menudo significa que falta la clave o que el formato Bearer es incorrecto. 403 a menudo significa que la clave funciona, pero la cuenta no puede usar el modelo o tiene saldo bajo. Y si uso salida en Base64, necesito añadir yo mismo el prefijo data:image/...;base64, antes de mostrarla en un navegador.

Comparación rápida

En resumen: esta guía muestra cómo configuraría la autenticación, construiría el cuerpo de la solicitud, elegiría entre T2I e I2I, gestionaría los trabajos asíncronos y guardaría el resultado sin perder archivos ni desperdiciar gasto.

2. Configura el acceso a la API y la autenticación

2.1 Crea tu cuenta de APIMart y genera una clave de API

Ve al sitio web de APIMart y regístrate para una nueva cuenta ^[8]. Luego abre la página de gestión de claves de API en tu panel y genera una clave de API ^[1][5].

Copia esa clave de inmediato y guárdala en el lado del servidor. Un gestor de secretos o una variable de entorno es el lugar más seguro para ella.

Nunca pongas tu clave de API en el código del frontend ni en un repositorio público. Si alguien obtiene esa clave, puede usar tu cuenta. En Node.js, guárdala con process.env.API_KEY. En un entorno de shell, usa export API_KEY="your-key-here" ^[1][6].

Antes de construir el flujo de solicitudes completo, envía una pequeña solicitud POST para asegurarte de que el acceso funciona ^[1][2]. Si obtienes una respuesta 200 OK, tu clave y permisos están configurados correctamente.

Después de eso, puedes pasar a los campos de la solicitud, incluidos el modelo y el prompt.

2.2 Establece la URL base y la cabecera de autenticación Bearer

Una vez que hayas elegido el modo T2I o I2I y tengas tu clave lista, necesitas configurar la autenticación antes de que funcione cualquier solicitud de imagen. Envía estas cabeceras con cada solicitud:

El prefijo Bearer importa. Si lo omites, la solicitud fallará ^[2][5]. Usa también exactamente un espacio después de Bearer.

Los códigos de estado HTTP te ayudan a detectar rápido los problemas de autenticación ^[1][10]. Un error 401 Unauthorized normalmente significa que la clave falta, es inválida o no se incluyó el prefijo Bearer ^[1][10]. Un error 403 Forbidden normalmente significa que la clave en sí es válida, pero la cuenta no tiene acceso al modelo o saldo suficiente ^[1][10].

Una buena forma de comprobar esto es probar primero con cURL. Si cURL funciona pero tu app no, el error probablemente esté en el código de solicitud de tu app ^[2][6].

Con la autenticación configurada, el siguiente paso es construir el cuerpo de la solicitud de imagen.

3. Construye una solicitud de imagen de Seedream 5.0 Pro

3.1 Campos requeridos: modelo, prompt, tamaño y número de imágenes

Con la autenticación configurada, el siguiente paso es construir el cuerpo JSON.

Un cuerpo de solicitud válido necesita cuatro campos: model, prompt, size y n.

Para Seedream 5.0 Pro, establece model en doubao-seedream-5-0-pro ^[1]. El campo prompt acepta una descripción en lenguaje natural y admite hasta 5.000 caracteres ^[2]. El campo size controla las dimensiones de salida o la relación de aspecto. Los valores comunes incluyen 1024x1024, 2K y relaciones de aspecto como 1:1 o 16:9 ^[1][2]. El campo n establece cuántas imágenes generar, normalmente de 1 a 15 ^[1][6].

Un pequeño detalle puede hacer tropezar a la gente: n debe ser un entero, no una cadena. Si pasas "1" en lugar de 1, la API devuelve un error de validación ^[1][5].

3.2 Campos opcionales: imágenes de referencia, búsqueda web y trabajos asíncronos

image_urls es el campo principal para el modo imagen a imagen. Úsalo para enviar hasta 14 imágenes de referencia como URL o URI de datos en Base64. Cada imagen debe pesar menos de 10 MB y usar una relación de aspecto entre 1:3 y 3:1 ^[1]. Si usas Base64, incluye el prefijo completo de URI de datos -data:image/jpeg;base64,- o la solicitud fallará ^[1][5].

web_search puede ayudar con prompts factuales o en tiempo real, como eventos actuales o logotipos de marca ^[4][7]. Para la mayoría de las generaciones de imágenes estándar, no lo necesitarás.

Para trabajos asíncronos o por lotes, callback_url acepta un endpoint HTTPS público donde APIMart hará un POST del payload de finalización de la tarea ^[2].

3.3 Ejemplos de llamadas a la API en cURL y JavaScript

Aquí tienes una solicitud cURL mínima funcional para una única imagen de 1024×1024:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedream-5-0-pro",
    "prompt": "A sunlit mountain trail in autumn, photorealistic, wide angle",
    "size": "1024x1024",
    "n": 1
  }'

Y aquí está la misma solicitud en Node.js con fetch:

const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "doubao-seedream-5-0-pro",
    prompt: "A sunlit mountain trail in autumn, photorealistic, wide angle",
    size: "1024x1024",
    n: 1
  })
});

const data = await response.json();
console.log(data);

Mantén esta solicitud en el lado del servidor. Nunca expongas tu clave de API en código del lado del cliente.

Una vez que envíes la solicitud, el siguiente paso es analizar el payload de la respuesta.

4. Gestiona las respuestas y ejecuta flujos de imagen comunes

4.1 Analiza las URL de imagen, la salida en Base64 y los objetos de error

Una vez que la solicitud termina, la forma de la respuesta se mantiene igual tanto si enviaste una imagen como varias.

Una respuesta exitosa devuelve un objeto JSON con cuatro campos de nivel superior: model, created (una marca de tiempo Unix), data (un array de objetos de imagen) y usage ^[6]. Cada imagen generada aparece dentro de data como una cadena url o b64_json, según el formato que pediste. Si n es mayor que 1, data incluye un objeto de imagen por cada salida.

Si usaste el formato URL, cada elemento en data almacena el enlace de la imagen en .url. Puedes establecer ese valor como el src de una imagen en el navegador. Un detalle: son enlaces firmados temporales, y caducan después de 24 horas ^[6]. Para apps de producción, descarga el archivo de inmediato y guárdalo en almacenamiento permanente en lugar de guardar la URL.

Si usaste el formato Base64, cada elemento en data almacena la cadena en bruto en .b64_json. No incluye el prefijo data:image/...;base64, ^[6]. Para mostrarla en un navegador, añade ese prefijo tú mismo:

img.src = "data:image/png;base64", + data.b64_json;

Para guardarla como archivo en Python, decodifícala primero:

import base64

image_data = base64.b64decode(response["data"][0]["b64_json"])
with open("output.png", "wb") as f:
    f.write(image_data)

Si la solicitud falla, la respuesta incluye un campo code y un campo message ^[6]. Un 400 normalmente significa un tamaño no compatible o un parámetro inválido. Un 401 significa que la solicitud no está autorizada. Registra ambos campos cada vez. En la mayoría de los casos, el message apunta directamente al problema.

Usa estos campos para decidir si debes almacenar, decodificar o mostrar la salida.

---

4.2 Tres tipos de imagen comunes que puedes generar con Seedream 5.0 Pro

Estos tres patrones se alinean con los modos tratados antes: solo texto, referencia única y múltiples referencias.

• Elementos visuales de marketing solo de texto. Para recursos de campaña que necesitan más detalle, usa la resolución 3K (size: "3K") y escribe un prompt estructurado que empiece con el sujeto y la disposición de la escena, y luego añada detalles de iluminación, estilo y color. La generación 3K tarda de 35 a 50 segundos, así que lo asíncrono suele ser el mejor encaje.

• Variaciones de producto con referencia única. Usa el modo imagen a imagen con una imagen de referencia en image_urls y un prompt enfocado que cambie solo lo que quieres, como el fondo, la iluminación o la textura de la superficie. Esto mantiene la forma y los detalles del producto más cerca de la imagen de origen que generar desde cero. Para variaciones 3K, usa callback_url, ya que cada tarea puede tardar unos 40 segundos ^[2].

• Consistencia con múltiples referencias para marca y personajes. Si necesitas que un personaje o un elemento de marca se mantenga consistente en varias imágenes, pasa hasta 14 imágenes de referencia a través de image_urls ^[2][3]. Establece sequential_image_generation en auto al crear múltiples salidas a partir de entradas de referencia para mantener la variedad sin perder la consistencia visual ^[5][4]. Esto funciona bien para series de contenido social, catálogos de producto y hojas de personaje.

Estos patrones tienden a funcionar mejor cuando el formato de respuesta coincide con el flujo de trabajo.

---

4.3 Solicitudes síncronas vs. asíncronas y respuestas URL vs. Base64

Usa esta comparación para elegir el formato de respuesta antes de lanzar la integración.

Para trabajos asíncronos, espera unos 20 segundos antes del primer sondeo y luego comprueba cada 3 segundos ^[2]. En producción, callback_url es la mejor opción porque evita los bucles de sondeo y reduce la sobrecarga del servidor ^[2][9].

Usa respuestas URL por defecto. Cambia a Base64 solo cuando necesites los datos de la imagen en la misma respuesta.

5. Lista de verificación final para una integración fiable de Seedream 5.0 Pro

Después de tu primera llamada de prueba exitosa, repasa esta lista antes de escalar a producción. Es una forma sencilla de detectar los problemas que suelen frenar en seco los lanzamientos.

Autenticación y seguridad de la clave. Mantén tu clave de API en una variable de entorno o un gestor de secretos. Envía las solicitudes desde tu backend con Authorization: Bearer <your_key>.

Valida los parámetros de tu solicitud antes de enviarlos. Comprueba la cadena del modelo, pasa n como entero, mantén image_urls dentro del límite permitido y asegúrate de que el size solicitado sea compatible.

Para trabajos que tardan más que una vista previa rápida, ajusta tu vía de entrega en consecuencia. Establece tiempos de espera según el tamaño de salida y usa callback_url para los trabajos de larga duración en lugar de sondeo.

Una vez que la imagen esté lista, trata la entrega como un problema de almacenamiento, no solo de respuesta. Si usas salida en URL, descarga el archivo de inmediato y muévelo a almacenamiento permanente. Las URL firmadas caducan después de 24 horas ^[6].

Prueba los prompts en un lote pequeño antes de escalar. Seedream 5.0 se cobra a unos 0,0320 $ por imagen generada ^[2]. Registra createTime, completeTime y costTime para poder vigilar la latencia y el gasto ^[2].

Preguntas frecuentes

¿Cómo compruebo un trabajo de imagen asíncrono después de obtener un task_id?

Usa el task_id devuelto para comprobar el estado de tu trabajo de imagen asíncrono.

Envía una solicitud GET al endpoint de estado que te da la API. En muchas API, eso se ve así:

• /v1/tasks/{task_id}
• o un endpoint de estilo consulta con el task_id

Para uso en producción, espera unos 20 segundos después de crear la tarea antes de tu primera comprobación de estado. Después de eso, sondea cada 3 segundos hasta que el estado del trabajo muestre completed.

Una vez que el trabajo esté hecho, lee el payload de la respuesta y extrae de él las URL de las imágenes.

¿Cuándo debería usar salida en URL en lugar de Base64?

Usa la salida en URL en la mayoría de los casos. Te da un enlace directo a la imagen generada, lo que facilita conectarla a apps web o móviles.

Usa Base64 solo cuando tu configuración necesite los datos de la imagen en línea en el cuerpo de la respuesta, como el procesamiento en memoria o cuando quieras evitar una segunda solicitud. Para recursos 4K de alta resolución, la salida en URL suele ser más eficiente.

¿Cuál es la mejor forma de evitar perder las imágenes generadas?

Guarda las imágenes generadas rápido, porque los enlaces de imagen de la API solo son válidos durante 72 horas.

La API de Seedream 5.0 Pro funciona de forma asíncrona. Eso significa que no obtendrás la URL de la imagen de inmediato. Primero obtienes un ID de tarea. Luego usas ese ID de tarea para obtener la URL de la imagen.

Para evitar perder la salida, tienes dos opciones principales:

• Sondear con el ID de tarea hasta que la imagen esté lista
• Usar una URL de callback para que tu sistema pueda recibir, capturar y almacenar la imagen antes de que el enlace caduque

Si esperas demasiado, la URL caducará y la imagen podría perderse.