API de Seedream 5.0 Lite: el endpoint de generación de imágenes más rápido

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

Resumen rápido

• POST /v1/images/generate - endpoint para imagen individual
• POST /v1/images/batch - hasta 50 imágenes por solicitud
• Latencia media de 5-15 segundos con soporte asíncrono y webhooks
• SDKs para Python y JavaScript disponibles (seedance / @seedance/sdk)
• Autenticación con token Bearer - genera tus claves en Configuración > Claves API

Descripción general de la API

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

La API sigue las convenciones REST con cuerpos de solicitud y respuesta en JSON. La generación es asíncrona: envías una solicitud, obtienes un ID de tarea y luego sondeas el estado o recibes un webhook cuando se completa.

Consulta la descripción completa de funciones en nuestro guía completa.

URL base

https://api.arteza.ai/v1

Características principales

Autenticación

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

Cómo obtener tu clave API

1. Regístrate 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

Verificar la autenticación

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

Respuesta:

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

Endpoint para imagen individual

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 la solicitud

Relaciones de aspecto

Estilos predefinidos

Formato de respuesta

Consultar el estado del resultado

GET /v1/images/{task_id}

En proceso:

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

Caducidad de la URL de imagen

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

¿Quieres un texto así de limpio? Prueba Seedream 5.0 Lite gratis →

Ejemplo en 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"
}

# Enviar 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"Tarea enviada: {task_id}")
print(f"Créditos cobrados: {task['credits_charged']}")
print(f"Créditos restantes: {task['credits_remaining']}")

# Consultar hasta que se complete
while True:
    result = requests.get(
        f"{BASE_URL}/images/{task_id}",
        headers=headers
    ).json()

    if result["status"] == "completed":
        print(f"Imagen lista: {result['image_url']}")
        break
    elif result["status"] == "failed":
        print(f"Error en la generación: {result.get('error', 'Error desconocido')}")
        break

    time.sleep(2)

Ejemplo en 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(`Tarea enviada: ${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 || 'Error en la generación');
    }

    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(`URL de la imagen: ${result.image_url}`);

Descargar las 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"Guardado: {filename}")

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

Endpoint para generación por lotes

Para generar varias imágenes en una sola solicitud:

POST /v1/images/batch

Solicitud por lotes

{
  "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 por lotes

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

Consultar el 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 por lotes

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

Integración de webhooks

Los webhooks eliminan la necesidad de sondear. Cuando se completa la generación, la API envía una solicitud POST a tu URL.

Carga útil 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', {})

        # Descargar 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)

        # Actualizar la base de datos
        update_generation_record(task_id, filename)

        print(f"Imagen guardada: {filename}")

    elif data['event'] == 'image.failed':
        print(f"Error en la generación: {data.get('error')}")

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

Seguridad del 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

Se controla mediante el parámetro booleano deep_thinking. Al activarlo, el modelo realiza un razonamiento adicional antes de la generación.

Cuándo activarlo

Impacto en el rendimiento

El pensamiento profundo añade aproximadamente 3-5 segundos, pero no consume créditos adicionales.

Gestión 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 uso y buenas prácticas

Límites de uso por plan

Buenas prácticas

1. Usa webhooks en lugar de sondeo - son más eficientes
2. Agrupa cuando sea posible - una solicitud por lotes supera a 50 solicitudes individuales
3. Retroceso exponencial - gestiona los límites de uso con elegancia
4. Guarda los resultados en caché - almacena las URL de imágenes y metadatos en tu base de datos
5. Descarga con rapidez - las URL de imágenes caducan a las 24 horas
6. Supervisa el saldo de créditos - revisa credits_remaining para evitar interrupciones
7. Usa metadatos - etiqueta las generaciones con IDs de proyecto para facilitar el seguimiento
8. Gestiona los errores con elegancia - no todas las generaciones tienen éxito

Instalación del 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 habituales

Integración con CMS

Genera imágenes destacadas automáticamente al crear una publicación:

@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 producto para e-commerce

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 para 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 del prompt de texto a la imagen generada, con soporte completo para pensamiento profundo, generación por lotes e integración de webhooks.

Obtén tu clave de API → - 10 créditos gratuitos, genera tu clave desde Configuración > Claves API y empieza a construir en minutos.