API Seedream v4.5: Integra Imágenes de IA en tu Aplicación

Integrar la generación de imágenes con IA en tu aplicación solía significar elegir entre tres opciones malas: ejecutar Stable Diffusion por tu cuenta (infraestructura costosa), pagar las tarifas por token de OpenAI (costos impredecibles), o comprometerse con una API de suscripción (capacidad desperdiciada). La API Seedream v4.5 está construida de forma diferente: pago por imagen a $0.10, REST estándar, y tiempos de respuesta medidos en segundos. Esta guía te lleva de cero a la primera generación en menos de 10 minutos.

Para qué es buena la API

La API Seedream v4.5 se ajusta a aplicaciones que necesitan generación de imágenes con IA bajo demanda con costos predecibles por imagen. Casos de uso comunes:

Productos SaaS que permiten a los usuarios generar imágenes como parte de su flujo de trabajo: herramientas de diseño, plataformas de marketing, aplicaciones de creación de contenido.

Plataformas de comercio electrónico que generan imágenes de estilo de vida de productos o encabezados de categorías mediante programación.

Herramientas de automatización de marketing que producen elementos visuales de campaña basados en entradas estructuradas.

Sistemas de gestión de contenidos que ofrecen generación de imágenes con IA como una característica nativa.

Proyectos de desarrolladores y scripts de automatización para cualquier flujo de trabajo que necesite generación de imágenes a escala.

Aplicaciones móviles que llaman a la API desde un servicio backend para mantener la generación de imágenes fuera del dispositivo.

Si tu caso de uso coincide con alguno de estos, esta guía te ayudará a integrarte rápidamente.

Autenticación y Primeros Pasos

Paso 1: Obtén una Clave API

Registrarse para una cuenta de Arteza si no tienes una. Navega a la configuración de tu cuenta y genera una clave API. Trata esta clave como una contraseña, no la confirmes en repositorios públicos.

Paso 2: Añade Créditos a Tu Cuenta

El uso de la API se extrae del mismo saldo de créditos que el uso en la web. Tus créditos gratuitos de registro de 10 funcionan en llamadas a la API. Para uso en producción, suscribete desde el página de precios comenzando en $5.

Paso 3: Realiza Tu Primer Solicitud

El endpoint de la API para Seedream v4.5 es:

POST https://api.arteza.ai/v1/images/generate

Cuerpo de solicitud mínimo:

{
  "model": "seedream-v4-5",
  "prompt": "Una librería acogedora al anochecer, luz cálida de la ventana",
  "width": 2048,
  "height": 2048,
  "num_images": 1
}

Incluye tu clave API en el encabezado de Autorización:

Authorization: Bearer YOUR_API_KEY

Referencia Completa de Parámetros

Resoluciones Soportadas

Seedream v4.5 soporta múltiples opciones de resolución hasta 4 megapíxeles:

Ejemplos de Código

Node.js (Fetch)

const generateImage = async (prompt) => {
  const response = await fetch(
    'https://api.arteza.ai/v1/images/generate',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SEEDANCE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'seedream-v4-5',
        prompt: prompt,
        width: 2048,
        height: 2048,
        num_images: 1,
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data = await response.json();
  return data.images[0].url;
};

// Uso
const imageUrl = await generateImage(
  'Una librería acogedora al anochecer, luz cálida de la ventana, fotografía editorial'
);
console.log(imageUrl);

Python (Requests)

import os
import requests

def generate_image(prompt, width=2048, height=2048, num_images=1):
    response = requests.post(
        'https://api.arteza.ai/v1/images/generate',
        headers={
            'Authorization': f'Bearer {os.environ["SEEDANCE_API_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'model': 'seedream-v4-5',
            'prompt': prompt,
            'width': width,
            'height': height,
            'num_images': num_images,
        },
    )
    response.raise_for_status()
    data = response.json()
    return [img['url'] for img in data['images']]

# Uso
urls = generate_image(
    'Una fotografía de producto editorial de una taza de cerámica de café, '
    'luz cálida de la mañana, composición minimalista'
)
print(urls)

cURL

curl -X POST https://api.arteza.ai/v1/images/generate \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-v4-5",
    "prompt": "Un skyline de ciudad futurista al atardecer, fotografía cinematográfica",
    "width": 2048,
    "height": 1152,
    "num_images": 1
  }'

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type GenerateRequest struct {
    Model     string `json:"model"`
    Prompt    string `json:"prompt"`
    Width     int    `json:"width"`
    Height    int    `json:"height"`
    NumImages int    `json:"num_images"`
}

func generateImage(prompt string) (string, error) {
    reqBody := GenerateRequest{
        Model:     "seedream-v4-5",
        Prompt:    prompt,
        Width:     2048,
        Height:    2048,
        NumImages: 1,
    }

    jsonData, _ := json.Marshal(reqBody)
    req, _ := http.NewRequest(
        "POST",
        "https://api.arteza.ai/v1/images/generate",
        bytes.NewBuffer(jsonData),
    )
    req.Header.Set("Authorization", "Bearer "+os.Getenv("SEEDANCE_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    images := result["images"].([]interface{})
    firstImage := images[0].(map[string]interface{})
    return firstImage["url"].(string), nil
}

Formato de Respuesta

Las respuestas exitosas devuelven JSON con esta estructura:

{
  "id": "gen_abc123xyz",
  "model": "seedream-v4-5",
  "created": 1712764800,
  "images": [
    {
      "url": "https://cdn.arteza.ai/gen/abc123.png",
      "width": 2048,
      "height": 2048,
      "seed": 42871
    }
  ],
  "credits_used": 8,
  "credits_remaining": 1042
}

Las URLs de imagen son válidas durante 24 horas. Descarga y almacena imágenes inmediatamente si necesitas acceso permanente.

¿Quieres este nivel de detalle? Prueba Seedream v4.5 gratis →

¿Listo para empezar a integrar? Obtén tu clave API →

Manejo de Errores

La API devuelve códigos de estado HTTP estándar:

Respuesta de error de ejemplo:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Tu cuenta tiene créditos insuficientes para esta solicitud",
    "credits_required": 8,
    "credits_available": 3
  }
}

Siempre implementa manejo de errores y reintentos para errores 429 y 500. No reintenters errores 400 y 401: requieren corregir la solicitud en sí.

Mejores Prácticas para Uso en Producción

Límite de Velocidad

Los límites de velocidad por defecto permiten un rendimiento razonable en producción. Si necesitas límites más altos, ponte en contacto con soporte con los detalles de tu caso de uso.

Implementa retroceso exponencial en errores 429:

import time

def generate_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return generate_image(prompt)
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            raise
    raise Exception("Max retries exceeded")

Gestión de Créditos

Monitorea el campo credits_remaining en cada respuesta. Configura alertas cuando el saldo caiga por debajo de un umbral para que puedas rellenarlo antes de que el tráfico de producción llegue a cero créditos.

def check_credits(response):
    remaining = response.json().get('credits_remaining', 0)
    if remaining < 100:
        send_alert(f'Advertencia de créditos bajos: {remaining} créditos')

Manejo Asincrónico

Para aplicaciones orientadas al usuario, trata la generación de imágenes como asincrónica. No bloquees el hilo de la interfaz de usuario en una llamada a la API de 5-15 segundos. Patrones:

• Devuelve un ID de trabajo inmediatamente, consulta la finalización
• Usa webhooks (si son compatibles) para notificaciones de finalización
• Genera especulativamente en el fondo y cachea los resultados

Almacenamiento en Caché

Las imágenes generadas son deterministas dado el mismo prompt y semilla. Cachea agresivamente por hash de prompt para evitar regenerar imágenes idénticas.

import hashlib

def prompt_cache_key(prompt, width, height, seed):
    raw = f'{prompt}|{width}x{height}|{seed}'
    return hashlib.sha256(raw.encode()).hexdigest()

Seguridad del Prompt

Si tu aplicación expone prompts a usuarios finales, implementa filtrado de contenido antes de enviar a la API. Arteza tiene políticas de contenido: los prompts que las violen devolverán errores, desperdiciando créditos y creando fallos orientados al usuario.

Precios para Uso de la API

El uso de la API se extrae del saldo de créditos de tu cuenta a la misma velocidad que el uso en la web.

Los créditos provienen del mismo niveles de precios independientemente de si los usas a través de web o API:

• Iniciante: $5 = 60 créditos al mes = 60 imágenes
• Creador: $25 = 300 créditos al mes = 300 imágenes
• Pro: $50 = 700 créditos al mes = 700 imágenes
• Estudio: $120 = 1,800 créditos al mes = 1,800 imágenes

Los clientes de mayor volumen pueden ponerse en contacto con soporte sobre precios por volumen para uso sostenido por encima de 100,000 imágenes/mes.

Combinación Con Otros Modelos de Arteza

Tu aplicación puede usar múltiples modelos de Seedance a través de la misma API cambiando el parámetro model:

• seedream-v4-5 - 1 créditos - calidad insignia
• seedream-v3 - 1 crédito - más rápido, más simple
• seedream-5-lite - 1 crédito - modo de pensamiento profundo
• seedream-5-edit - 1 crédito - edición de imágenes
• seedance-2 - generación de video (endpoint diferente)

Para aplicaciones que necesitan capacidades de edición además de generación, seedream-5-edit maneja la edición de imágenes basada en texto. Consulta el Documentación de Seedream 5 Edit para más detalles.

Consideraciones de Seguridad

Nunca expongas claves API del lado del cliente. Siempre enruta las llamadas a la API a través de tu backend. Las claves expuestas pueden usarse para agotar tu saldo de créditos.

Rota claves periódicamente. Si una clave se ve comprometida, revócala y genera una nueva.

Registra solicitudes para depuración. Incluye IDs de solicitud en tus registros para que puedas correlacionar fallos con respuestas de la API.

Implementa cuotas de uso por usuario. Si tu aplicación ofrece generación con IA como una característica, limita el consumo por usuario para prevenir abuso.

Preguntas Frecuentes

¿Hay un nivel gratuito para la API? Tus 10 créditos de registro funcionan en llamadas a la API. Eso es 10 generaciones gratuitas de Seedream v4.5 para probar la integración antes de pagar.

¿Cuál es el tiempo de respuesta típico? 5-15 segundos para Seedream v4.5 dependiendo de la resolución y la carga actual.

¿Puedo usar la API para productos comerciales? Sí. El uso comercial está incluido. Las imágenes generadas de tus clientes son suyas para usar para cualquier propósito legítimo.

¿Hay un SDK de Python? Los SDKs oficiales están en desarrollo. La API REST actual funciona bien con bibliotecas HTTP estándar en cualquier idioma.

¿Cómo manejo errores de política de contenido? Implementa mensajes orientados al usuario que expliquen que el prompt fue rechazado. Registra el error específico para depuración.

¿Qué pasa si mis créditos se agotan durante una solicitud? La API devuelve un error 402 antes de que comience la generación. Los cargos parciales nunca ocurren: obtienes la imagen completa u obtienes un error.

¿Puedo agrupar múltiples prompts en una solicitud? No directamente. Usa num_images: 6 para obtener variaciones del mismo prompt, o haz llamadas a la API paralelas para diferentes prompts.

---

La API Seedream v4.5 te proporciona generación de imágenes con IA lista para producción con precios predecibles por imagen y convenciones REST estándar. Para la mayoría de integraciones, puedes pasar de clave API a la primera generación funcional en menos de 10 minutos. Para preguntas o precios por volumen, ponte en contacto a través de tu panel de control de cuenta.

Comienza a integrar hoy. Obtén tu clave API → | Ver precios completos → | Lee la guía v4.5 →