Referencia de la API de Vellria

Envía tu clave de API como token Bearer en el encabezado Authorization de cada solicitud. Las claves empiezan con el prefijo vll_ y se crean en la página Claves de API.

Authorization: Bearer vll_...

GET/v1/models

Los modelos, tamaños y resoluciones válidos, con su costo en créditos. Lee este endpoint en lugar de fijar una lista de precios en tu código. Cada tamaño incluye ratio y tier junto a su etiqueta, así que nunca tienes que analizar la etiqueta para saber la relación de aspecto o el nivel de resolución (un ratio adaptive significa que el resultado toma sus proporciones de la imagen de entrada), y cada modelo incluye max_prompt_length, el límite de caracteres que ese modelo aplica a prompt (y a cualquier parámetro de texto libre que no declare el suyo). Cada modelo incluye también developer, la empresa que lo creó (null en un modelo que se ofrece con el nombre Vellria).

curl https://vellria.com/v1/models \
  -H "Authorization: Bearer vll_..."

POST/v1/generate/image

curl https://vellria.com/v1/generate/image \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-lite",
    "prompt": "A cat asleep in space, cinematic light",
    "size": "1024*1024",
    "seed": 42
  }'

• model: vellria-lite · size: 1024*1024 | 1536*1024 | 1024*1536 | 2048*1152 | 1152*2048 | 2048*2048 · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · 1 crédito en todos los tamaños
• model: vellria-seedream5-pro · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (predeterminado: enabled) · 8 créditos en todos los tamaños
• model: vellria-seedream5-pro-edit · imagen a imagen · image_urls: 1–10 URL https (obligatorio) · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (predeterminado: enabled) · 8 créditos en todos los tamaños + 1 crédito por cada imagen de referencia después de la primera
• model: vellria-qwen-3-image · size: 1024*1024 | 1536*1024 | 1024*1536 | 2048*1152 | 1152*2048 | 2048*2048 · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · negative_prompt: texto, como máximo 10000 caracteres · 5 créditos en todos los tamaños
• model: vellria-qwen-3-image-edit · imagen a imagen · image_urls: 1–3 URL https (obligatorio) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · negative_prompt: texto, como máximo 10000 caracteres · 5 créditos en todos los tamaños + 1 crédito por cada imagen de referencia después de la primera
• model: vellria-qwen-3-pro-image · size: 1024*1024 | 1536*1024 | 1024*1536 · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · negative_prompt: texto, como máximo 10000 caracteres · 7 créditos en todos los tamaños
• model: vellria-qwen-3-pro-edit · imagen a imagen · image_urls: 1–3 URL https (obligatorio) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · negative_prompt: texto, como máximo 10000 caracteres · 7 créditos en todos los tamaños + 1 crédito por cada imagen de referencia después de la primera
• model: vellria-seedream5-lite · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 créditos en todos los tamaños
• model: vellria-seedream5-lite-edit · imagen a imagen · image_urls: 1–14 URL https (obligatorio) · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 créditos en todos los tamaños
• model: vellria-wan26-image · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1440*1440 | 1920*1080 | 1080*1920 · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · negative_prompt: texto, como máximo 10000 caracteres · 6 créditos en todos los tamaños
• model: vellria-wan26-image-edit · imagen a imagen · image_urls: 1–4 URL https (obligatorio) · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1664*936 | 936*1664 · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · negative_prompt: texto, como máximo 10000 caracteres · 6 créditos en todos los tamaños
• model: vellria-wan27-image-edit · imagen a imagen · image_urls: 1–9 URL https (obligatorio) · size: 2K · seed: entero 0–2147483647, aleatorio si se omite y se devuelve en la respuesta · 6 créditos en todos los tamaños

POST/v1/generate/video

curl https://vellria.com/v1/generate/video \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vellria-seedance-2-5-video",
    "prompt": "Ocean waves at sunset, slow dolly forward",
    "duration": 5,
    "resolution": "1080p"
  }'

• model: vellria-seedance-2-5-video · duration: 4–30 segundos · resolution: 480p | 720p | 1080p · 480p 28 · 720p 60 · 1080p 120 créditos/s
• model: vellria-seedance-2-5-image-video · imagen a video · image_urls: 1–1 URL https (obligatorio) · duration: 4–30 segundos · resolution: 480p | 720p | 1080p · 480p 28 · 720p 60 · 1080p 120 créditos/s
• model: vellria-seedance-2-0-fast-video · duration: 4–15 segundos · resolution: 480p | 720p | 720p-SR | 1080p-SR | 1440p-SR · ratio: adaptive | 21:9 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480p 5 · 720p 10 · 720p-SR 8 · 1080p-SR 17 · 1440p-SR 30 créditos/s
• model: vellria-seedance-2-0-fast-image-video · imagen a video · image_urls: 1–1 URL https (obligatorio) · duration: 4–15 segundos · resolution: 480p | 720p | 720p-SR | 1080p-SR | 1440p-SR · ratio: adaptive | 21:9 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480p 5 · 720p 10 · 720p-SR 8 · 1080p-SR 17 · 1440p-SR 30 créditos/s
• model: vellria-minimax-h3-video · duration: 4–15 segundos · resolution: 480P | 768P | 1440p-sr | 4k-sr · ratio: 21:9 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480P 5 · 768P 7 · 1440p-sr 12 · 4k-sr 16 créditos/s
• model: vellria-minimax-h3-image-video · imagen a video · image_urls: 1–1 URL https (obligatorio) · duration: 4–15 segundos · resolution: 480P | 768P | 1440p-sr | 4k-sr · 480P 5 · 768P 7 · 1440p-sr 12 · 4k-sr 16 créditos/s
• model: vellria-minimax-h3-max-video · duration: 5–15 segundos · resolution: 480P | 768P | 1440p-sr | 4k-sr · ratio: 21:9 | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480P 8 · 768P 15 · 1440p-sr 30 · 4k-sr 50 créditos/s
• model: vellria-minimax-h3-max-image-video · imagen a video · image_urls: 1–1 URL https (obligatorio) · duration: 5–15 segundos · resolution: 480P | 768P | 1440p-sr | 4k-sr · 480P 8 · 768P 15 · 1440p-sr 30 · 4k-sr 50 créditos/s
• model: vellria-happyhorse-1-1-video · duration: 3–15 segundos · resolution: 480p | 720p | 1080p · ratio: 21:9 | 16:9 | 5:4 | 4:3 | 1:1 | 3:4 | 4:5 | 9:16 | 9:21 · 480p 11 · 720p 22 · 1080p 29 créditos/s
• model: vellria-happyhorse-1-1-image-video · imagen a video · image_urls: 1–1 URL https (obligatorio) · duration: 3–15 segundos · resolution: 480p | 720p | 1080p · 480p 11 · 720p 22 · 1080p 29 créditos/s
• model: vellria-wan-3-video · duration: 2–30 segundos · resolution: 480p | 720p | 1080p · ratio: adaptive | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480p 8 · 720p 16 · 1080p 32 créditos/s
• model: vellria-wan-3-image-video · imagen a video · image_urls: 1–1 URL https (obligatorio) · duration: 2–30 segundos · resolution: 480p | 720p | 1080p · 480p 8 · 720p 16 · 1080p 32 créditos/s
• model: vellria-wan-3-pro-video · duration: 2–30 segundos · resolution: 480p | 720p | 1080p · ratio: adaptive | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480p 11 · 720p 22 · 1080p 45 créditos/s
• model: vellria-wan-3-pro-image-video · imagen a video · image_urls: 1–1 URL https (obligatorio) · duration: 2–30 segundos · resolution: 480p | 720p | 1080p · 480p 11 · 720p 22 · 1080p 45 créditos/s

POST/v1/uploads

No necesitas alojar tú mismo las imágenes de referencia: envía el archivo a este endpoint como cuerpo sin procesar, recibe una URL pública y usa esa URL en image_urls. El encabezado Content-Type es obligatorio y debe coincidir con el cuerpo; los tipos aceptados son image/jpeg, image/png, image/webp, image/bmp e image/gif, con un límite de 20 MB por archivo. Una imagen que se usa como referencia debe ser un JPEG, PNG, GIF o WebP estático de 20 MB como máximo, sin áreas transparentes. Los metadatos, como EXIF, se eliminan cuando se guarda el archivo. La URL lleva un ID imposible de adivinar y se conserva durante el mismo período que los archivos generados; cuando expira, el endpoint devuelve HTTP 410 y content_expired. La URL del archivo de una generación (/v1/generations/{id}/file) requiere autenticación y no se puede usar como referencia: los endpoints de generación la rechazan con HTTP 400 y el código reference_not_public antes de gastar créditos. En su lugar, sube el archivo aquí o convierte una generación de imagen en una URL de referencia pública con POST /v1/generations/{id}/reference. Cada imagen de referencia enviada a POST /v1/generate/image o POST /v1/generate/video se revisa automáticamente, una tras otra, antes de gastar créditos: todas las personas que aparecen deben ser adultas (las imágenes sin personas se aceptan), se rechaza una imagen que muestre a una persona real conocida y también una con texto dirigido a la verificación, como instrucciones o afirmaciones sobre la edad. Una solicitud rechazada devuelve HTTP 400 con el código image_blocked y un motivo (minor, public_figure o image_text), sin indicar a qué imagen se refiere; una imagen que no se puede leer devuelve HTTP 400 e image_unreadable, con reason animated, transparent o too_large cuando esa es la causa. Cada referencia se guarda primero como archivo subido (una imagen indicada con una URL externa se copia, sin sus metadatos) y tanto la verificación como el proveedor descargan esa misma URL de subida, así que el proveedor recibe exactamente el archivo verificado. Si la verificación no está disponible, la solicitud devuelve HTTP 503 y moderation_unavailable y no se cobra nada, así que las generaciones con imágenes de referencia dependen de que la verificación esté disponible. Las generaciones sin imágenes de referencia no se revisan de esta forma.

curl https://vellria.com/v1/uploads \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: image/png" \
  --data-binary @reference.png

GET/v1/generations/{id}

Las generaciones se ejecutan de forma asíncrona; el estado pasa por queued → processing → completed (en cola → procesando → completada). Los créditos se reembolsan automáticamente cuando una generación falla.

curl https://vellria.com/v1/generations/{id} \
  -H "Authorization: Bearer vll_..."

GET/v1/projects

Las carpetas agrupan tus generaciones y nada más: no cuestan créditos y nunca tocan un archivo. Crea una con POST /v1/projects (un nombre de 1 a 64 caracteres, como máximo 100 carpetas por cuenta), renómbrala con POST /v1/projects/{id} y elimínala con DELETE /v1/projects/{id}. Eliminar una carpeta nunca elimina generaciones: las filas se conservan y su project_id pasa a null. Para poner una generación en una carpeta usa POST /v1/generations/{id}/project, y para sacarla envía project_id: null al mismo endpoint. Para leerlas, GET /v1/generations?project={id} devuelve una carpeta y GET /v1/generations?project=none devuelve las generaciones que no están en ninguna carpeta. La lista se pagina con limit (1–50, 20 por defecto) y offset; cada página incluye has_more y total, el número de generaciones que coinciden con los mismos filtros.

curl https://vellria.com/v1/projects \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Campaign" }'

curl -X POST https://vellria.com/v1/generations/{id}/project \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "prj_..." }'

curl "https://vellria.com/v1/generations?project=none" \
  -H "Authorization: Bearer vll_..."

POST/v1/billing/create-checkout

Los créditos se compran en una página de pago alojada. GET /v1/billing/packages devuelve una única lista de paquetes, cada uno con un id, un precio usd y sus créditos, junto con min_usd y max_usd para un monto libre; lee estos valores del endpoint en lugar de fijarlos en tu código. POST /v1/billing/create-checkout recibe un package_id de esa lista o un price_amount libre en USD entre 20 y 10000, redondeado a centavos; un monto libre se convierte con la misma tarifa fija que los paquetes. Si se envían ambos, gana package_id y el precio y los créditos salen del catálogo. Un package_id desconocido devuelve HTTP 400 con el código invalid_package y un monto fuera del rango devuelve invalid_amount. Puede haber como máximo cinco pagos abiertos a la vez; uno más devuelve HTTP 429 hasta que alguno se pague, se cancele o expire. La respuesta es el registro del pago con un checkout_url: envía ahí a quien paga para que complete el pago en la página segura de nuestro proveedor de pagos, donde los métodos disponibles dependen de su país. Los créditos se agregan automáticamente cuando se confirma el pago; consulta el estado con GET /v1/billing/payments/{id}. POST /v1/billing/payments/{id}/cancel marca un pago abierto como cancelado; si se completa de todos modos, los créditos se agregan.

curl https://vellria.com/v1/billing/create-checkout \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{ "package_id": "pack_20" }'

curl https://vellria.com/v1/billing/create-checkout \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{ "price_amount": 25 }'

Los archivos generados se conservan 14 días y luego se eliminan del servidor. El registro sigue en tu historial de facturación, pero ya no se puede acceder al archivo. La respuesta de GET /v1/generations incluye el campo retention_days y cada generación incluye expires_at; pedir un archivo expirado devuelve HTTP 410 con el código content_expired. Descarga todo lo que necesites conservar por más tiempo. También puedes terminar antes el período de conservación: DELETE /v1/generations/{id} elimina de inmediato el archivo guardado y registra purged_at, exactamente como lo haría la limpieza programada. La fila de la generación nunca se elimina, así que los créditos que costó siguen visibles en tu historial y no se reembolsan, y el endpoint del archivo responde a partir de ahí con el mismo HTTP 410 y content_expired. Eliminar dos veces no es un error y devuelve el mismo resultado; una generación que todavía está en queued o processing aún no se puede eliminar y devuelve HTTP 409 con el código generation_in_progress.

curl -X DELETE https://vellria.com/v1/generations/{id} \
  -H "Authorization: Bearer vll_..."

DELETE/v1/account

Al cerrar tu cuenta se eliminan tus generaciones y sus archivos guardados, tus archivos subidos, tus claves de API y tus mensajes de soporte, y se cierra tu sesión. Los créditos que queden en la cuenta se pierden y no se reembolsan. Los registros de pago se conservan como registros de facturación, así que una cuenta cerrada sigue apareciendo en el historial de pagos que estamos obligados a conservar. El endpoint solo se autentica con la sesión: se llama desde la página Cuenta de la consola, y una solicitud que lleve una clave de API se rechaza con HTTP 403. Una cuenta con un pago aún sin liquidar no se puede cerrar y devuelve HTTP 409 con el código pending_payment, porque ese pago todavía puede acreditarse; el mismo 409 con merge_in_progress se devuelve mientras la cuenta se vincula con otra. En ambos casos, espera un momento y vuelve a intentarlo.

20 imágenes y 10 videos por minuto. Las generaciones con imágenes de referencia también comparten un límite de 120 intentos por hora, incluidos los rechazados; al superarlo, los endpoints de generación devuelven el código reference_rate_limited. Superar un límite devuelve HTTP 429; espera el tiempo que indica el encabezado Retry-After y vuelve a intentarlo.

Tu prompt no se reescribe ni se suaviza antes de llegar al modelo: si un modelo ofrece un reescritor de prompts como opción, lo enviamos desactivado. Lo que queda es un filtro de seguridad acotado y una lista corta de reglas; aquí está completa.

• Una verificación automática revisa el texto del prompt antes de cobrar ningún crédito y rechaza lo que reconoce de una lista fija de categorías: contenido sexual con menores, zoofilia, incesto entre parientes consanguíneos, sexo no consentido, violencia extrema y gore, contenido de cámara oculta o voyerista, y la solicitud de un intercambio de rostros o deepfake, o una que nombre a una persona real conocida; la prohibición en sí es más amplia que lo que detecta esa verificación. Las imágenes de referencia se revisan automáticamente de la misma forma antes de cobrar ningún crédito: se rechaza una imagen que muestre a alguien que pueda tener menos de 21 años o a una persona real conocida, y también una con texto dirigido a la verificación. Ninguna de las dos verificaciones identifica a una persona real común, no famosa; representarla sin su consentimiento está prohibido por los términos, pero no se detecta automáticamente. Tanto la regla sobre menores como la regla sobre contenido no consentido son de tolerancia cero; según los términos, un incumplimiento cierra la cuenta sin previo aviso.
• El proveedor que ejecuta un modelo aplica su propio filtro de seguridad y puede rechazar una solicitud ya iniciada; la generación se marca como fallida y los créditos cobrados al inicio se reembolsan automáticamente.