API Seedream 5.0 Lite: Endpoint de Generación de Imágenes más Rápido

API REST, autenticación Bearer, generación asíncrona, webhooks, batches nativos de hasta 50 imágenes por solicitud. Todo lo disponible en la interfaz web de Arteza también está en la API. Aquí está la referencia completa con ejemplos funcionales de Python y JavaScript que puedes copiar a producción hoy.

Descripción General de la API

La API de Seedream 5.0 Lite proporciona acceso programático al pipeline de generación de imágenes en la plataforma Arteza. Todo en la interfaz web, texto a imagen, pensamiento profundo, transferencia de estilo, renderizado de texto, está en la API REST.

La API sigue convenciones REST con cuerpos de solicitud y respuesta en JSON. La generación es asíncrona: envía una solicitud, obtén un ID de tarea y luego consulta o recibe un webhook cuando esté completa.

Vista general completa de características en nuestra guía completa.

URL Base

https://api.arteza.ai/v1

Características Clave

Autenticación

Autenticación por token Bearer. Genera tu clave API desde el panel de Arteza en Configuración > Claves API.

Obtén tu Clave API

1. Registrarse o inicia sesión en tu cuenta de Arteza
2. Ve a Configuración > Claves API
3. Haz clic en Generar Nueva Clave
4. Copia y guarda tu clave de forma segura (se muestra solo una vez)

Encabezado de Autenticación

Authorization: Bearer YOUR_API_KEY

Prueba de Autenticación

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.arteza.ai/v1/account/credits

Respuesta:

{
  "credits_remaining": 1050,
  "tier": "starter"
}

Endpoint de Imagen Única

POST /v1/images/generate

Solicitud Mínima

{
  "model": "seedream-5.0-lite",
  "prompt": "A serene mountain landscape at sunrise"
}

Solicitud Completa

{
  "model": "seedream-5.0-lite",
  "prompt": "Professional YouTube thumbnail with text 'TOP 10 TIPS' in bold red font, excited person on left, bright blue background",
  "aspect_ratio": "16:9",
  "deep_thinking": true,
  "style": "photorealistic",
  "webhook_url": "https://your-app.com/webhook/image-complete",
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  }
}

Respuesta

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "credits_remaining": 1043,
  "estimated_time_seconds": 10
}

Parámetros de Solicitud

Relaciones de Aspecto

Presets de Estilo

Formato de Respuesta

Consulta de Resultados

GET /v1/images/{task_id}

En procesamiento:

{
  "task_id": "img_abc123def456",
  "status": "processing",
  "progress": 0.65,
  "estimated_time_remaining": 5
}

Completado:

{
  "task_id": "img_abc123def456",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "image_url_webp": "https://cdn.arteza.ai/generated/img_abc123def456.webp",
  "width": 1024,
  "height": 1024,
  "model": "seedream-5.0-lite",
  "deep_thinking_used": true,
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails",
    "batch_id": "thumb-2026-04"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Expiración de URL de Imagen

Las URL de imágenes generadas son válidas durante 24 horas. Descarga y almacena imágenes en tu propio almacenamiento dentro de esta ventana.

¿Quieres texto tan limpio? Prueba Seedream 5.0 Lite gratis →

Ejemplo de Python

import requests
import time

API_KEY = "your_api_key_here"
BASE_URL = "https://api.arteza.ai/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Envía solicitud de generación
response = requests.post(
    f"{BASE_URL}/images/generate",
    headers=headers,
    json={
        "model": "seedream-5.0-lite",
        "prompt": "A futuristic city skyline at sunset with flying cars",
        "aspect_ratio": "16:9",
        "deep_thinking": True
    }
)

task = response.json()
task_id = task["task_id"]
print(f"Task submitted: {task_id}")
print(f"Credits charged: {task['credits_charged']}")
print(f"Credits remaining: {task['credits_remaining']}")

# Consulta para finalización
while True:
    result = requests.get(
        f"{BASE_URL}/images/{task_id}",
        headers=headers
    ).json()

    if result["status"] == "completed":
        print(f"Image ready: {result['image_url']}")
        break
    elif result["status"] == "failed":
        print(f"Generation failed: {result.get('error', 'Unknown error')}")
        break

    time.sleep(2)

Ejemplo de JavaScript

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://api.arteza.ai/v1';

async function generateImage(prompt, options = {}) {
  const response = await fetch(`${BASE_URL}/images/generate`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'seedream-5.0-lite',
      prompt,
      aspect_ratio: options.aspectRatio || '1:1',
      deep_thinking: options.deepThinking || false,
      ...options
    })
  });

  const task = await response.json();
  console.log(`Task submitted: ${task.task_id}`);

  while (true) {
    const result = await fetch(
      `${BASE_URL}/images/${task.task_id}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    ).then(r => r.json());

    if (result.status === 'completed') {
      return result;
    }
    if (result.status === 'failed') {
      throw new Error(result.error || 'Generation failed');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

// Uso
const result = await generateImage(
  'A cozy coffee shop interior with warm lighting',
  { aspectRatio: '16:9', deepThinking: true }
);
console.log(`Image URL: ${result.image_url}`);

Descargar Imágenes Generadas

import requests

def download_image(image_url, filename):
    response = requests.get(image_url)
    with open(filename, 'wb') as f:
        f.write(response.content)
    print(f"Saved: {filename}")

download_image(result['image_url'], 'output/my_image.png')

Endpoint de Generación por Lotes

Para múltiples imágenes en una solicitud única:

POST /v1/images/batch

Solicitud de Lote

{
  "generations": [
    {
      "prompt": "Minimalist logo design, blue circle with lightning bolt",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": true
    },
    {
      "prompt": "Professional headshot background, soft gradient",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "1:1",
      "deep_thinking": false
    },
    {
      "prompt": "YouTube thumbnail with text 'MUST WATCH' in red",
      "model": "seedream-5.0-lite",
      "aspect_ratio": "16:9",
      "deep_thinking": true
    }
  ],
  "webhook_url": "https://your-app.com/webhook/batch-complete"
}

Respuesta de Lote

{
  "batch_id": "batch_xyz789",
  "status": "processing",
  "total_generations": 3,
  "total_credits_charged": 21,
  "credits_remaining": 1029
}

Consulta del Estado del Lote

GET /v1/images/batch/{batch_id}

{
  "batch_id": "batch_xyz789",
  "status": "completed",
  "results": [
    {
      "index": 0,
      "status": "completed",
      "task_id": "img_001",
      "image_url": "https://cdn.arteza.ai/generated/img_001.png"
    },
    {
      "index": 1,
      "status": "completed",
      "task_id": "img_002",
      "image_url": "https://cdn.arteza.ai/generated/img_002.png"
    },
    {
      "index": 2,
      "status": "completed",
      "task_id": "img_003",
      "image_url": "https://cdn.arteza.ai/generated/img_003.png"
    }
  ]
}

Límites de Lote

Para flujos de trabajo por lotes, consulta nuestro guía de generación masiva.

Integración de Webhooks

Los webhooks eliminan la consulta. Cuando la generación se completa, la API realiza una solicitud POST a tu URL.

Payload del Webhook

{
  "event": "image.completed",
  "task_id": "img_abc123def456",
  "batch_id": "batch_xyz789",
  "status": "completed",
  "image_url": "https://cdn.arteza.ai/generated/img_abc123def456.png",
  "model": "seedream-5.0-lite",
  "credits_charged": 7,
  "metadata": {
    "project": "youtube-thumbnails"
  },
  "created_at": "2026-04-10T14:30:00Z"
}

Ejemplo de Manejador (Python/Flask)

from flask import Flask, request, jsonify
import requests

app = Flask(__name__)

@app.route('/webhook/image-complete', methods=['POST'])
def handle_image_webhook():
    data = request.json

    if data['event'] == 'image.completed':
        task_id = data['task_id']
        image_url = data['image_url']
        metadata = data.get('metadata', {})

        # Descarga imagen
        img_response = requests.get(image_url)
        filename = f"images/{metadata.get('project', 'default')}/{task_id}.png"
        with open(filename, 'wb') as f:
            f.write(img_response.content)

        # Actualiza tu base de datos
        update_generation_record(task_id, filename)

        print(f"Image saved: {filename}")

    elif data['event'] == 'image.failed':
        print(f"Generation failed: {data.get('error')}")

    return jsonify({'status': 'ok'}), 200

Seguridad de Webhook

Verifica la autenticidad del webhook mediante el encabezado X-Seedance-Signature:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Modo de Pensamiento Profundo

Controlado por el parámetro booleano deep_thinking. Cuando está habilitado, el modelo realiza razonamiento adicional antes de la generación.

Cuándo Habilitar

Impacto de Rendimiento

El pensamiento profundo añade ~3-5 segundos pero cuesta cero créditos adicionales.

Manejo de Errores

Formato de Respuesta de Error

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to complete this generation. Required: 7, Available: 3",
    "status": 402
  }
}

Códigos de Error

Estrategia de Reintento

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                f"{BASE_URL}/images/generate",
                headers=headers,
                json={
                    "model": "seedream-5.0-lite",
                    "prompt": prompt
                }
            )

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 5))
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Retroceso exponencial

Límites de Velocidad y Mejores Prácticas

Límites de Velocidad por Nivel

Mejores Prácticas

1. Usa webhooks en lugar de consulta - más eficiente
2. Procesa por lotes cuando sea posible - una solicitud de lote vence a 50 solicitudes individuales
3. Retroceso exponencial - maneja límites de velocidad con gracia
4. Cachea resultados - almacena URL de imágenes y metadatos en tu base de datos
5. Descarga rápidamente - las URL de imágenes vencen después de 24 horas
6. Monitorea saldo de créditos - verifica credits_remaining para evitar interrupciones
7. Usa metadatos - etiqueta generaciones con IDs de proyecto para seguimiento
8. Maneja errores con gracia - no todas las generaciones tienen éxito

Instalación de SDK

Python:

pip install seedance

from seedance import SeedanceClient

client = SeedanceClient(api_key="your_key")
result = client.images.generate(
    model="seedream-5.0-lite",
    prompt="A beautiful sunset",
    deep_thinking=True
)

JavaScript:

npm install @seedance/sdk

import { SeedanceClient } from '@seedance/sdk';

const client = new SeedanceClient({ apiKey: 'your_key' });
const result = await client.images.generate({
    model: 'seedream-5.0-lite',
    prompt: 'A beautiful sunset',
    deepThinking: true
});

Patrones de Integración Comunes

Integración de CMS

Genera imágenes destacadas automáticamente en la creación de publicaciones:

@app.route('/cms/webhook/new-post', methods=['POST'])
def handle_new_post():
    post = request.json

    result = generate_image(
        prompt=f"Blog header image for article about {post['title']}, "
               f"professional editorial style, 16:9",
        aspect_ratio="16:9",
        deep_thinking=True,
        metadata={"post_id": post["id"]}
    )

    update_post_featured_image(post["id"], result["image_url"])

Imágenes de Productos de Comercio Electrónico

def generate_product_images(product):
    prompts = [
        f"Product photo of {product.name}, white background, studio lighting, 1:1",
        f"Lifestyle photo of {product.name} in use, natural setting, 16:9",
        f"Product detail close-up of {product.name}, macro photography, 1:1"
    ]

    batch = client.images.batch_generate(
        generations=[
            {"model": "seedream-5.0-lite", "prompt": p}
            for p in prompts
        ]
    )

    return batch

Automatización de Redes Sociales

def generate_weekly_social_content(brand, topics):
    generations = []
    for topic in topics:
        generations.append({
            "model": "seedream-5.0-lite",
            "prompt": f"{brand.style_prefix} {topic}, social media post, 1:1",
            "aspect_ratio": "1:1",
            "deep_thinking": True,
            "metadata": {"topic": topic, "platform": "instagram"}
        })

    return client.images.batch_generate(generations=generations)

---

La API de Seedream 5.0 Lite es el camino más rápido de un prompt de texto a una imagen generada con soporte completo para pensamiento profundo, generación por lotes e integración de webhooks.

Obtén tu clave API → - 50 créditos gratis, genera tu clave desde Configuración > Claves API, comienza a construir en minutos.