Guía de API de Seedream 5.0 Pro: genera y edita imágenes con código

La API de Seedream 5.0 Pro ofrece a los desarrolladores acceso al modelo insignia de generación y edición de imágenes de ByteDance mediante un flujo de trabajo asíncrono orientado a producción. Esta guía muestra cómo enviar tareas de texto a imagen y edición de imágenes a través de Poyo.ai, y después obtener el resultado mediante consultas periódicas de estado o un webhook.

El precio actual es de 15 créditos, aproximadamente $0.075 por imagen generada, para ambas variantes del modelo.

Modelos y parámetros de la API

Flujo de trabajo	ID del modelo
Texto a imagen	seedream-5.0-pro
Edición de imágenes	seedream-5.0-pro-edit

Las entradas compatibles incluyen:

• prompt: instrucción obligatoria de generación o edición
• size: un ajuste predefinido de resolución como 1K o 2K, o una relación de aspecto como 1:1, 4:3, 3:4, 16:9 o 9:16
• n: número de imágenes que se generarán
• output_format: jpeg o png
• image_urls: imágenes de referencia para el modelo de edición, hasta 10
• callback_url: endpoint HTTPS opcional para recibir notificaciones de finalización

Consulta la referencia de API en vivo para ver el esquema actual.

1. Crear una clave API

Crea una cuenta en Poyo.ai, abre Gestión de claves API y guarda la clave en una variable de entorno. Nunca expongas una clave de producción en código del navegador ni la subas a Git.

export POYO_API_KEY="your-api-key"

2. Enviar una solicitud de texto a imagen

Todos los trabajos utilizan el endpoint unificado de envío:

POST https://api.poyo.ai/api/generate/submit

cURL

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro",
    "callback_url": "https://example.com/webhooks/poyo",
    "input": {
      "prompt": "Editorial science magazine cover about clean energy cities, title \"THE ELECTRIC CITY\", structured grid, accurate icons, dark navy and electric green palette",
      "size": "3:4",
      "n": 1,
      "output_format": "png"
    }
  }'

La respuesta contiene un ID de tarea:

{
  "code": 200,
  "data": {
    "task_id": "task-unified-example",
    "status": "not_started",
    "created_time": "2026-07-16T10:10:00"
  }
}

3. Llamar a Seedream 5.0 Pro con JavaScript

const API_URL = 'https://api.poyo.ai/api/generate/submit';

async function generateSeedreamImage(prompt) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.POYO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'seedream-5.0-pro',
      input: {
        prompt,
        size: '2K',
        n: 1,
        output_format: 'png',
      },
    }),
  });

  const payload = await response.json();
  if (!response.ok || payload.code !== 200) {
    throw new Error(payload.error?.message || 'Seedream request failed');
  }
  return payload.data.task_id;
}

Usa 2K cuando la resolución sea más importante que una proporción fija. Usa un valor de relación de aspecto cuando el formato de colocación sea la principal restricción.

4. Llamar a Seedream 5.0 Pro con Python

import os
import requests

API_URL = "https://api.poyo.ai/api/generate/submit"

def generate_seedream_image(prompt: str) -> str:
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['POYO_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "seedream-5.0-pro",
            "input": {
                "prompt": prompt,
                "size": "16:9",
                "n": 1,
                "output_format": "jpeg",
            },
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("code") != 200:
        raise RuntimeError(payload.get("error", {}).get("message", "Request failed"))
    return payload["data"]["task_id"]

5. Editar imágenes con múltiples referencias

Cambia el ID del modelo y proporciona image_urls. Indica al modelo qué aporta cada referencia.

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header "Authorization: Bearer $POYO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "seedream-5.0-pro-edit",
    "input": {
      "prompt": "Use the room from reference 1. Replace only the chair with the chair from reference 2. Put the logo from reference 3 on the wall. Preserve the original camera, windows, floor, and afternoon lighting.",
      "image_urls": [
        "https://example.com/room.jpg",
        "https://example.com/chair.png",
        "https://example.com/logo.png"
      ],
      "size": "16:9",
      "n": 1,
      "output_format": "png"
    }
  }'

Para conseguir ediciones fiables, separa el prompt en tres ideas: funciones de las referencias, cambios solicitados y restricciones de conservación.

6. Obtener el resultado

El envío es asíncrono. Después de recibir task_id, puedes:

• consultar el endpoint unificado de estado de tareas de Poyo.ai; o
• proporcionar callback_url y procesar el webhook de finalización.

Sigue la documentación de gestión de tareas para consultar la ruta de estado actual y el objeto de respuesta. En producción, utiliza un retroceso exponencial en lugar de realizar consultas continuas.

Gestión de errores

Gestiona estos casos de forma explícita:

• 400: parámetros de modelo no válidos, tamaños no compatibles, URLs de imagen inaccesibles o JSON mal formado
• 401: clave API ausente o no válida
• tarea asíncrona fallida: la generación falló después de un envío válido
• reintento de webhook: el mismo evento de finalización puede entregarse más de una vez

Guarda el ID de tarea junto con tu ID de trabajo interno, haz que la gestión de webhooks sea idempotente y registra los mensajes de error del proveedor sin almacenar secretos.

Lista de comprobación para producción

• Mantén las claves API en el servidor.
• Valida la longitud del prompt y los tipos de URL de imagen antes del envío.
• Usa imágenes de referencia HTTPS a las que el servicio de generación pueda acceder.
• Configura tiempos de espera para las llamadas de envío.
• Reintenta errores de red temporales, pero no repitas solicitudes no válidas sin comprobarlas.
• Calcula el coste como number of requested outputs × 15 credits con los precios actuales.
• Revisa el texto generado, los detalles de producto y las afirmaciones de carácter factual antes de publicar.
• Añade una moderación de contenido adecuada para tu producto y mercado.

Cuándo usar Pro en lugar de Lite

Usa Seedream 5.0 Pro para diseños estructurados, composiciones densas, texto multilingüe y ediciones controladas. Usa Seedream 5.0 Lite para trabajos de imagen de menor coste y mayor volumen en los que no sea necesaria la precisión de diseño de nivel Pro.

Para una explicación no técnica, lee características y precios de Seedream 5.0 Pro. También puedes probar visualmente la carga útil de la API en la página del modelo Seedream 5.0 Pro.

Preguntas frecuentes

¿Cuál es el endpoint de la API de Seedream 5.0 Pro?

Envía las tareas de generación y edición a POST https://api.poyo.ai/api/generate/submit.

¿Cuál es el ID del modelo de edición?

Usa seedream-5.0-pro-edit e incluye uno o más valores en input.image_urls.

¿Cuántas imágenes de referencia son compatibles?

La documentación actual de Poyo.ai admite hasta 10 imágenes de referencia para la edición con Seedream 5.0 Pro.

¿Cuánto cuesta una imagen mediante la API?

El precio actual de Poyo.ai es de 15 créditos, aproximadamente $0.075, por cada imagen generada o editada.