API de edición de Seedream v4.5: edición de imágenes programática

Usar Seedream v4.5 Edit desde la interfaz de Arteza es ideal para ediciones puntuales y lotes pequeños. Para flujos de trabajo de gran volumen, como catálogos con miles de SKUs, generación dinámica de imágenes por usuario o pipelines de activos gestionados por un CMS, necesitas acceso a la API. Esta guía explica la estructura del endpoint, los parámetros de solicitud, el manejo de respuestas y los patrones de producción para construir sistemas automatizados de edición de imágenes con Seedream v4.5.

Resumen rápido

• Seedream v4.5 Edit está disponible en el endpoint fal-ai/bytedance/seedream/v4.5/edit
• Mismo precio de 1 créditos ($0,10) por imagen que en la interfaz
• Acepta hasta 10 URLs de imágenes de entrada más un prompt de texto
• Salida de 4 MP (2048×2048) devuelta como URL de imagen
• Tiempo de generación habitual de 30-60 segundos: usa patrones asíncronos en producción

Por qué usar la API

La API desbloquea patrones de automatización que la interfaz no puede igualar:

• Procesamiento en lotes de gran volumen. Procesa más de 1.000 ediciones en una sola ejecución del pipeline.
• Generación dinámica. Crea imágenes bajo demanda a partir de datos de usuario o registros de base de datos.
• Flujos de trabajo programados. Actualizaciones nocturnas del catálogo, regeneración activada por eventos.
• Integración con stacks existentes. Node.js, Python, Go, Ruby: cualquier cliente HTTP.
• Producción reproducible. Scripts con control de versiones en lugar de clics manuales.

Si tu caso de uso implica más de 20-50 ediciones similares, la API vale la pena configurarla.

Estructura del endpoint

El modelo Seedream v4.5 Edit está disponible en:

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

Es un endpoint estándar de fal.ai que se puede invocar directamente o a través del sistema de créditos de Arteza.

Autenticación

Las solicitudes a la API de Arteza se autentican mediante una clave API que se pasa en el encabezado Authorization como token Bearer.

Cómo obtener tu clave API

1. Inicia sesión en arteza.ai
2. Ve a la configuración de tu cuenta
3. Busca la sección de API
4. Genera una nueva clave API
5. Guárdala de forma segura: trátala como una contraseña

Nunca incluyas tu clave API en el control de versiones. Usa variables de entorno:

export SEEDANCE_API_KEY="your_api_key_here"

Encabezado de autenticación

Authorization: Bearer your_api_key_here

Estructura de la solicitud

Una solicitud básica a Seedream v4.5 Edit tiene este aspecto:

{
  "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"
}

Referencia de parámetros

Se pueden pasar hasta 10 URLs de imagen. El modelo trata la primera imagen como la principal y las siguientes como referencias.

Ejemplo de solicitud: 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);

Ejemplo de solicitud: 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"])

Estructura de la respuesta

Una respuesta exitosa incluye las URLs de las imágenes generadas:

{
  "images": [
    {
      "url": "https://storage.arteza.ai/output/abc123.png",
      "width": 2048,
      "height": 2048,
      "content_type": "image/png"
    }
  ],
  "seed": 123456789,
  "credits_used": 8
}

Descarga la imagen desde la URL devuelta: las URLs de salida son válidas durante 24 horas.

Patrón de generación asíncrona

Seedream v4.5 Edit tarda entre 30 y 60 segundos por solicitud. En producción conviene usar generación asíncrona con webhooks o sondeo en lugar de solicitudes bloqueantes.

Asíncrono basado en webhooks

Pasa una webhook_url en tu solicitud y Arteza hará un POST con el resultado cuando finalice la generación:

{
  "prompt": "...",
  "image_urls": ["..."],
  "webhook_url": "https://your-app.com/webhooks/seedream"
}

Tu manejador de webhook recibe:

{
  "request_id": "req_abc123",
  "status": "completed",
  "images": [
    {
      "url": "https://storage.arteza.ai/output/xyz.png"
    }
  ]
}

El manejo por webhook es el patrón recomendado en producción.

Empieza a construir. Prueba la herramienta primero.

Asíncrono basado en sondeo

Si tu infraestructura no puede recibir webhooks, consulta el estado mediante sondeo:

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

// Sondear hasta que finalice
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;
}

Sondea cada 5-10 segundos. El tiempo de espera total suele ser de 30-60 segundos.

Patrones de producción

Patrón 1: Generación en lote para catálogos

Ejecuta la API sobre tu catálogo de productos para generar cambios de fondo consistentes en cada 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"])

Combínalo con un manejador de webhook que guarde los resultados en tu CDN y actualice el registro del producto.

Patrón 2: Ediciones de usuario bajo demanda

Permite que los usuarios suban imágenes y obtengan resultados editados por IA al momento:

1. El usuario sube la imagen a tu bucket
2. Tu backend llama a Seedream v4.5 Edit con un prompt elegido por el usuario
3. Sondea o espera el webhook
4. Devuelve la URL del resultado al cliente del usuario

Prevé un tiempo de espera de aproximadamente 60 segundos por edición en tu experiencia de usuario.

Patrón 3: Pipeline de activos gestionado por CMS

Cuando se publica contenido en tu CMS, genera automáticamente las imágenes asociadas:

1. El CMS emite un evento de publicación
2. Se activa una función serverless
3. Llama a Seedream v4.5 Edit con un prompt de plantilla
4. Almacena el resultado en el CDN
5. Actualiza el registro del CMS con la URL de la imagen

Este patrón elimina la creación manual de imágenes en flujos de publicación de gran volumen.

Manejo de errores

Respuestas de error más habituales:

Envuelve siempre las llamadas a la API en bloques try/except con lógica de reintento para respuestas 429 y 500.

Límites de tasa

Arteza aplica límites de tasa razonables en la API. En la mayoría de los flujos de producción no los alcanzarás, pero para lotes masivos de más de 1.000 solicitudes, implementa:

• Retroceso exponencial ante respuestas 429
• Límites de solicitudes concurrentes (empieza con 5 en paralelo y ajusta al alza)
• Colas de solicitudes para un rendimiento predecible

Contacta con el soporte para obtener límites de tasa más altos en cargas de producción intensivas.

Coste a escala de API

Las llamadas a la API tienen el mismo precio que las de la interfaz: 1 créditos ($0,10) por imagen. A efectos de planificación:

• 100 llamadas a la API = 100 créditos (dentro del plan Starter de $5)
• 1.000 llamadas a la API = 1.000 créditos (plan Studio de $120, 1.800 al mes)
• 10.000 llamadas a la API = 10.000 créditos (plan Studio de $120 más unos 8.200 créditos en recargas adicionales)

Para volúmenes superiores a 10.000 al mes, contacta con el equipo para precios personalizados.

Buenas prácticas

1. Usa webhooks en producción. El sondeo funciona, pero desperdicia recursos.
2. Guarda los prompts en control de versiones. Trátalos como código.
3. Registra todo. IDs de solicitud, prompts, resultados y errores.
4. Valida las entradas antes de llamar. Las URLs de imagen incorrectas desperdician créditos.
5. Monitoriza el saldo de créditos. Configura alertas cuando baje de un umbral.
6. Prueba los cambios de prompt en staging. Valida con 3-5 imágenes antes de ejecutar un lote completo.
7. Almacena en caché los resultados. Si las entradas son idénticas, reutiliza los resultados anteriores.

Lectura adicional

• Guía completa de edición de Seedream v4.5
• Tutorial de edición por lotes
• Desglose de precios

Primeros pasos

Genera tu clave API en el panel de Arteza, obtén 10 créditos gratis y ejecuta el ejemplo de Node.js con una foto de producto. La API desbloquea todo el potencial de producción de Seedream v4.5 Edit: una vez integrada, el resto es ingeniería de prompts. Si prefieres hacer pruebas antes de automatizar, Abrir la herramienta web y valida tus prompts primero.