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

Ejecutar Seedream v4.5 Edit a través de la interfaz de Arteza funciona para ediciones puntuales y lotes pequeños. Para flujos de trabajo de alto volumen - catálogos con miles de SKU, generación de imágenes dinámica por usuario, canalizaciones de activos impulsadas por CMS - necesitas acceso a la API. Esta guía te lleva a través de la estructura del endpoint, parámetros de solicitud, manejo de respuestas y patrones de producción para crear sistemas de edición de imágenes automatizados en Seedream v4.5.

Resumen

• Seedream v4.5 Edit está disponible a través del endpoint fal-ai/bytedance/seedream/v4.5/edit
• Los mismos 8 créditos ($0.08) por imagen que en la interfaz
• Acepta hasta 10 URLs de imagen de entrada más un prompt de texto
• Salida de 4MP (2048×2048) devuelta como URL de imagen
• Tiempo de generación típico de 30-60 segundos - usa patrones asincronos para producción

Por qué usar la API

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

• Procesamiento por lotes de alto volumen. Procesa 1.000+ ediciones en una única ejecución de canalización.
• Generación dinámica. Construye imágenes bajo demanda a partir de datos de usuario o registros de base de datos.
• Flujos de trabajo programados. Actualizaciones de catálogo nocturnas, regeneración activada por eventos.
• Integración con stacks existentes. Node.js, Python, Go, Ruby - cualquier cliente HTTP.
• Producción reproducible. Scripts controlados por versiones en lugar de clics manuales.

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

Estructura del Endpoint

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

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

Este es un endpoint de modelo estándar de fal.ai que puede ser llamado directamente o a través del sistema de créditos de Arteza.

Autenticación

Las solicitudes a la API de Arteza se autentican a través de una clave API pasada en el encabezado Authorization como un token Bearer.

Obtén tu Clave API

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

Nunca confirmes 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 Solicitud

Una solicitud básica de Seedream v4.5 Edit se ve así:

{
  "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 imágenes posteriores como referencias.

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

Solicitud de Ejemplo: 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 Respuesta

Una respuesta exitosa incluye las URLs de imagen 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 Asincrónica

Seedream v4.5 Edit tarda 30-60 segundos por solicitud. Para producción probablemente quieras generación asincrónica con webhooks o polling en lugar de solicitudes bloqueantes.

Async Basado en Webhook

Pasa una webhook_url en tu solicitud y Arteza hará POST del resultado a ella cuando se complete 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 de webhook es el patrón de producción recomendado.

Comienza a construir. Prueba la herramienta primero.

Async Basado en Polling

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

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

// Poll for completion
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;
}

Consulta cada 5-10 segundos. La espera total es usualmente de 30-60 segundos.

Patrones de Producción

Patrón 1: Generación de Lote de Catálogo

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

Empareja con un manejador de webhook que guarde salidas 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 con IA bajo demanda:

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

Presupuesta aproximadamente 60 segundos de tiempo de espera por edición en tu UX.

Patrón 3: Canalización de Activos Impulsada por CMS

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

1. CMS emite un evento de publicación
2. Función sin servidor se activa
3. Llama a Seedream v4.5 Edit con un prompt de plantilla
4. Almacena resultado en CDN
5. Actualiza registro de CMS con URL de imagen

Este patrón elimina la creación manual de imágenes para publicación de alto volumen.

Manejo de Errores

Respuestas de error comunes:

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

Límites de Velocidad

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

• Retroceso exponencial en respuestas 429
• Límites de solicitud concurrente (comienza en 5 en paralelo, ajusta hacia arriba)
• Colas de solicitud para rendimiento predecible

Contacta con soporte para límites de velocidad más altos en cargas de trabajo de producción pesada.

Costo a Volumen de API

Las llamadas a la API cuestan lo mismo que las llamadas de interfaz: 8 créditos ($0.08) por imagen. Para propósitos de planificación:

• 100 llamadas a API = 800 créditos (nivel Starter, $10)
• 1.000 llamadas a API = 8.000 créditos (nivel Pro, $50)
• 10.000 llamadas a API = 80.000 créditos (múltiples niveles Studio, aprox. $650)

Para volúmenes por encima de 10.000/mes, contacta al equipo para precios personalizados.

Mejores Prácticas

1. Usa webhooks en producción. El polling funciona pero desperdicia recursos.
2. Almacena prompts en control de versiones. Trata los prompts como código.
3. Registra todo. IDs de solicitud, prompts, salidas, errores.
4. Valida entradas antes de llamar. Las URLs de imagen incorrectas desperdician créditos.
5. Monitorea el saldo de créditos. Alerta cuando caigas por debajo de un umbral.
6. Prueba cambios de prompt en staging. Valida en 3-5 imágenes antes de ejecutar un lote completo.
7. Cachea resultados. Si las entradas son idénticas, reutiliza salidas anteriores.

Lectura Adicional

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

Comienza

Genera tu clave API en el panel de Arteza, obtén 50 créditos gratis y ejecuta el ejemplo de Node.js anterior con una foto de producto. La API desbloquea el potencial de producción completo de Seedream v4.5 Edit - una vez que la tengas conectada, todo lo demás es ingeniería de prompts. Para pruebas prácticas primero, abrir la herramienta web y valida tus prompts antes de automatizar.