Seedream 5.0 Pro · API

Inicio rápido

Tres pasos: envía un trabajo, consúltalo y toma el enlace de la imagen. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

Paso 1 · Envía el trabajo (devuelve al momento un id de trabajo, HTTP 202)

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.0-pro", "prompt": "La puerta de un café en un callejón al atardecer, una pizarra que dice «Hoy: latte de osmanto 4 €», un gato atigrado al lado, fotorrealista", "size": "16:9", "resolution": "2K"}'

Respuesta (HTTP 202)

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedream-5.0-pro"
}

Paso 2 · Consulta cada 2–3 segundos hasta que status sea succeeded o failed

curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"

Respuesta cuando sale bien

{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedream-5.0-pro",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.jpg"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "seedream-5.0-pro"}
}

Paso 3 · data[0].url es la imagen (el JPEG original). Se guarda 7 días; descárgala en tu propio almacenamiento para conservarla más tiempo.

Ejemplo completo (Python: enviar, esperar y guardar en disco)

import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. enviar el trabajo
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "seedream-5.0-pro",
    "prompt": "La puerta de un café en un callejón al atardecer, una pizarra que dice «Hoy: latte de osmanto 4 €», un gato atigrado al lado, fotorrealista",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 3 segundos hasta que termine
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. descargar la imagen
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedream-5.0-pro.jpg", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])

Autenticación

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Crea una clave API en la consola para empezar.

Parámetros de la petición

El cuerpo JSON de POST /v1/images/generations:

Los demás parámetros de OpenAI (quality, background, output_format, style y similares) no se admiten: no tienen efecto ni cambian el precio. El resultado es siempre el JPEG original, devuelto como url; con response_format: "b64_json" el resultado incluye además una copia en base64.

Precio

Se cobra por imagen, solo según el nivel: la proporción y que sea texto a imagen o imagen a imagen no cambian nada. El precio del nivel se retiene al enviar y se reembolsa íntegro si el trabajo falla. 1 crédito = $0.005.

Proporción, resolución y tamaño de salida

Pon la proporción en size y el nivel en resolution. Recibes el original que el modelo dibuja en esa proporción, sin recortes ni redimensionado; su tamaño es como mínimo el de la tabla y algunas proporciones salen más grandes (1K 16:9 es ahora 1536×864).

• Solo se admiten las 8 proporciones de la tabla; cualquier otra (5:4, 2:1...) devuelve 400 unsupported_size al enviar y no se cobra nada. Algunos tamaños nativos difieren un 1–3% de la proporción nominal (1K 4:3 es 1104×848): es el tamaño que dibuja el propio modelo. Antes de entregar se comprueban la proporción y el modelo que figura en la credencial C2PA, y que el tamaño sea como mínimo el de la tabla; si algo no coincide, la imagen no se entrega, el trabajo falla y no se cobra nada.
• size también puede ser un tamaño en píxeles (p. ej. 2560x1440): solo fija la proporción (a menos de un 1,5% de una de las 8) y recibes igualmente el original en esa proporción (como mínimo del tamaño de la tabla). El nivel lo da resolution; sin él decide el lado más largo: hasta 1536 es 1K, de 1537 a 2600 es 2K.
• Este modelo solo tiene 1K y 2K: pedir 4K (resolution: "4K", o un size con el lado largo mayor de 2600) se rechaza al momento con 400 unsupported_resolution y no se cobra nada. Para 2K, envía resolution: "2K".

Imagen a imagen e imágenes de referencia

• Envía image (una imagen) o images (varias, hasta 8; las que pasen de 8 no se usan) y el trabajo será de imagen a imagen; indica en el prompt qué cambiar. POST /v1/images/edits acepta los mismos parámetros.
• Los dos endpoints solo aceptan un cuerpo JSON, no la subida de archivos multipart, así que images.edit() del SDK de OpenAI no se puede usar tal cual: pasa enlaces o base64 como en el ejemplo de abajo.
• Cada referencia puede ser una URL pública de imagen (http o https), un data: URI o base64 puro, de hasta 16MB cada una, en un formato habitual como JPEG, PNG o WebP.
• La URL tiene que descargar directamente la imagen: no puede ser una página web ni estar detrás de un inicio de sesión o de una protección contra hotlinking. Una referencia que no podemos leer se rechaza al enviar con un 400 que indica cuál es y por qué; no se crea ningún trabajo y no se cobra nada.
• En ediciones y fusiones la proporción de salida sigue a size (1:1 si falta), no a la imagen de referencia; para mantener la proporción del original, pon esa proporción en size. Recibes el original del modelo, sin recortes ni redimensionado.
• Alojamos las referencias por ti y las guardamos 7 días.

Imagen a imagen con dos referencias

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.0-pro", "prompt": "Mantén a las personas y cambia el fondo por una playa de noche con guirnaldas de luces cálidas", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'

Estado y campos del trabajo

GET /v1/images/jobs/{id} devuelve estos estados; cada campo se describe en Trabajos asíncronos. Consulta cada 2–3 segundos o usa un webhook.

Cada cuenta ejecuta hasta 50 trabajos a la vez; los demás esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa íntegro. Los registros de trabajos se guardan 3 días y los enlaces de las imágenes, 7 días.

Cuánto tarda

Normalmente 40–90 segundos desde el envío hasta el resultado; 2K y varias referencias tardan algo más y a veces pasan de 2 minutos.

Llamadas reales de los últimos 7 días: mediana 88 s; el 90% termina en 2.5 min o menos.

Errores y reembolsos

Un error al enviar se devuelve al momento como HTTP 4xx / 5xx: no se crea ningún trabajo y no se cobra nada. Un fallo después de que el trabajo fue aceptado lo informa el endpoint del trabajo, y la retención se reembolsa íntegra. Todos los códigos están en Códigos de error.

Errores al enviar

Trabajos fallidos (status failed)

Webhooks en lugar de consultas

Añade callback_url al enviar y, en cuanto termine el trabajo, con éxito o con error, la pasarela enviará a esa URL exactamente lo mismo que devuelve el endpoint de consulta, firmado y con reintentos si la entrega falla. También puedes configurar una dirección para toda la cuenta en Configuración → Webhook, en la consola. Documentación de webhooks →

curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedream-5.0-pro", "prompt": "La puerta de un café en un callejón al atardecer, una pizarra que dice «Hoy: latte de osmanto 4 €», un gato atigrado al lado, fotorrealista", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'