API de 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 tasas por token de OpenAI (costos impredecibles) o comprometerse con una API de suscripción (capacidad desperdiciada). La API Seedream v4.5 está construida de manera diferente: paga por imagen a $0.08, 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é sirve la API

La API Seedream v4.5 es adecuada para 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ía 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 contenido que ofrecen generación de imágenes con IA como 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

Regístrate para una cuenta de Arteza si no tienes una. Ve 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 web. Tus 50 créditos gratuitos de registro funcionan en llamadas API. Para uso en producción, suscríbete desde el página de precios a partir de $10.

Paso 3: Realiza tu primera solicitud

El punto final 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 atardecer, luz cálida de las ventanas",
  "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 atardecer, luz cálida de las ventanas, 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 para 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 horizonte 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 las imágenes son válidas durante 24 horas. Descarga y almacena las 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 reintentar errores 400 y 401: esos requieren arreglar la solicitud en sí.

Mejores prácticas para uso en producción

Limitación de velocidad

Los límites de velocidad predeterminados permiten un rendimiento razonable en producción. Si necesitas límites más altos, contacta 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 baje de un umbral para que puedas recargar antes de que el tráfico en 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édito bajo: {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 API de 5-15 segundos. Patrones:

• Devuelve un ID de trabajo inmediatamente, sondea la finalización
• Utiliza webhooks (si se admiten) para notificaciones de finalización
• Genera especulativamente en segundo plano y cachea resultados

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 visibles para el usuario.

Precios para uso de API

El uso de la API se extrae del saldo de créditos de tu cuenta al mismo ritmo que el uso web.

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

• Starter: $10 = 1.050 créditos = ~131 imágenes
• Popular: $25 = 2.750 créditos = ~343 imágenes
• Creator: $50 = 5.750 créditos = ~718 imágenes
• Studio: $100 = 12.000 créditos = ~1.500 imágenes

Los clientes con mayor volumen pueden contactar 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 utilizar múltiples modelos de Seedance a través de la misma API cambiando el parámetro model:

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

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

Consideraciones de seguridad

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

Rota las 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 de IA como característica, limita el consumo por usuario para prevenir abuso.

Preguntas frecuentes

¿Hay un nivel gratuito para la API? Tus 50 créditos de registro funcionan en llamadas API. Son 6 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 carga actual.

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

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

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

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

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

---

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 primera generación funcional en menos de 10 minutos. Para preguntas o precios por volumen, comunícate a través de tu panel de control de cuenta.

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