Referencia de la API de Vellria

Cada entrada incluye id (el valor que envías como model), label, kind (image o video), family y developer, la empresa que lo creó (null en un modelo que se ofrece con el nombre Vellria), además de dos modos, text y reference: envía solo un prompt y el modelo se ejecuta en modo text —una llamada text-to-image o text-to-video—; adjunta una o más imágenes de referencia a ese mismo id y se ejecuta en modo reference en su lugar —image-to-image o image-to-video—, no hay un id separado para elegir entre los dos. Cada modo incluye sus propios sizes (imagen) o resolutions (video), un default, max_prompt_length (el límite de caracteres que ese modo aplica a prompt, y a cualquier parámetro de texto libre que no declare el suyo) y parameters. Cada tamaño o resolución 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). reference_images es null en modo text; en modo reference incluye el mínimo y el máximo de imágenes de referencia que ese modo acepta, extra_credits cobrados por cada referencia después de la primera, y los límites de archivo que debe cumplir una imagen de referencia. Un modelo cuyos huecos de referencia tienen roles fijos los enumera en orden en reference_images.roles (null en todos los modelos por ahora): la primera URL de image_urls tomaría el primer rol, cada URL siguiente el siguiente, y el último rol se repetiría para el resto.

Los créditos del tamaño elegido se cobran al iniciar la generación y se reembolsan automáticamente si falla. Los tamaños, límites de referencia, parámetros y precios de cada modelo salen de GET /v1/models.

El modo subject solo existe en los modelos cuya entrada de GET /v1/models trae un bloque subject (null en los demás); ese bloque indica sus propias resoluciones, duraciones, proporciones y parámetros, el límite de referencias en subject.reference_images.max y el patrón del token en subject.reference_token. Cuesta lo mismo que imagen a video en ese modelo, sin cargo por referencia. Errores, todos HTTP 400 y antes de gastar créditos: invalid_reference_mode si el valor no es frame ni subject o el modelo no tiene modo subject; invalid_image_urls si el modo subject no recibe ninguna referencia o recibe más de las que admite el modelo; invalid_reference_token si el prompt cita un @image sin referencia que le corresponda (por ejemplo, @image3 con dos imágenes). En modo frame, @image1 es texto normal.

Es compatible con OpenAI: apunta cualquier SDK de OpenAI a la URL base de Vellria con tu clave vll_. Cada respuesta se cobra por token de tus créditos.

Por 1M de tokens: entrada 50 créditos (USD 0.50) · entrada en caché 5 créditos (USD 0.05) · salida 200 créditos (USD 2.00).

• Las respuestas no tienen filtro: Vellria no añade moderación de contenido a este endpoint, así que moderar a tus propios usuarios finales es responsabilidad tuya. Antes de tus mensajes se añade una instrucción de identidad de una línea; sus tokens no se cobran y no cuentan en usage.
• Imágenes: añade partes image_url a un mensaje user, como mucho 4 por mensaje y 8 por solicitud. Sube primero la imagen con POST /v1/uploads y pasa la URL devuelta; las data URL se rechazan con data_url_not_supported.
• max_tokens vale 1024 por defecto y como mucho 4096. Los campos de razonamiento (reasoning, thinking) se ignoran y las respuestas nunca contienen razonamiento.
• Con stream: true la respuesta llega como eventos del servidor (líneas data:) en el formato de fragmentos de OpenAI y termina con data: [DONE]. El fragmento anterior tiene choices vacío y lleva usage y el cobro. Un error tras empezar el streaming llega como evento data: {"error": …}; si ya se envió texto, ese texto se cobra (el fragmento con usage llega justo antes del error); si no, no se cobra nada.
• Cada respuesta lleva usage de OpenAI más credits_charged (créditos fraccionarios), cost_usd y credits_debited (créditos enteros descontados ahora del saldo; las fracciones se acumulan en tu cuenta). Las respuestas rechazadas, fallidas o vacías no se cobran; un streaming que cancelas se cobra por los tokens ya generados.
• El saldo debe cubrir la respuesta más larga posible antes de empezar (si no, 402 insufficient_credits). Las solicitudes por minuto y las que se ejecutan a la vez están limitadas por cuenta (429 rate_limit_exceeded).

import OpenAI from "openai"

const client = new OpenAI({
  apiKey: "vll_...",
  baseURL: "https://vellria.com/v1",
})

const stream = await client.chat.completions.create({
  model: "vellria-uncensored-chat",
  messages: [{ role: "user", content: "Empecemos una historia." }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

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 y dentro de los límites de archivo que publica el modelo elegido: `GET /v1/models` los devuelve por modelo en `reference_images.limits` (bytes, lado en píxeles y megapíxeles). Una referencia fuera de esos límites se rechaza con HTTP 400 e `image_unreadable`, con motivo `too_small` o `too_large`, antes de gastar créditos. Los metadatos, como EXIF, se eliminan cuando se guarda el archivo. La URL lleva un ID imposible de adivinar y se elimina 24 horas después de la subida si ninguna generación la usa (campo expires_at de la respuesta); si se usa como referencia en una generación, se conserva 48 horas desde la subida, mucho menos 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. Las imágenes de referencia no pasan ningún control de contenido: ninguna imagen se rechaza por quién o qué muestra, y en esta ruta no existe el rechazo image_blocked. Nosotros solo rechazamos una referencia cuando el propio archivo no se puede leer: una imagen que no se puede leer devuelve HTTP 400 e image_unreadable, con reason animated, transparent too_small o too_large cuando esa es la causa. El propio modelo aún puede rechazar una imagen de referencia que no logra procesar; esa generación falla con error_code reference_rejected y sus créditos se reembolsan automáticamente. Si una referencia no se puede preparar, la solicitud devuelve HTTP 503 y reference_unavailable, sin gastar créditos. Los prompts enviados con una clave de API llegan al modelo tal como se envían; solo se rechazan las solicitudes que implican abuso sexual de menores, con HTTP 400 y el código content_blocked. Cada referencia se guarda primero como archivo subido (una imagen indicada con una URL externa se copia, sin sus metadatos) y el proveedor descarga esa misma URL fijada, así que el proveedor recibe exactamente el archivo guardado.

La lista de GET /v1/generations solo muestra generaciones completadas y en curso: una generación fallida queda fuera de la lista y de su total, mientras que GET /v1/generations/{id} la sigue devolviendo con su error_code durante 30 días; después el registro fallido se elimina y GET /v1/generations/{id} y el endpoint del archivo devuelven HTTP 404 con el código not_found. Filtrar la lista con ?status=failed devuelve 400, y las generaciones fallidas tampoco cuentan en la mitad de generaciones de GET /v1/billing/history (generations_total incluido). Los fallos que aún no se te han notificado se listan en GET /v1/generations/failures: count, refunded_cents (créditos realmente reembolsados, 0 si no hubo reembolso), until y hasta 5 de los más recientes en data. Márcalos como vistos con POST /v1/generations/failures/seen enviando ids (de 1 a 50 ids de generación) o until (todos los fallos hasta esa marca de tiempo); los ids de otras cuentas se ignoran y un fallo se notifica una sola vez, en cualquier dispositivo.

POST /v1/billing/create-checkout recibe un package_id de esa lista o un price_amount libre en USD entre 30 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 pague en USD con tarjeta (Visa o Mastercard) en la página segura de nuestro proveedor de pagos. 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. El campo opcional provider elige el proveedor que cobra el pago; los valores aceptados son whop (tarjeta), nowpayments (cripto) y telegram_stars (Estrellas de Telegram). GET /v1/billing/packages enumera en providers los proveedores abiertos para el checkout, y el primero es el predeterminado si no se envía el campo. Un proveedor desconocido o cerrado devuelve HTTP 400 con el código invalid_provider, y una lista providers vacía significa que los pagos no están disponibles en este momento. Cada paquete indica además en excluded_providers los proveedores que no pueden cobrarlo, por ejemplo telegram_stars cuando el paquete supera el límite de factura de Telegram Stars; un checkout de ese paquete con un proveedor excluido devuelve HTTP 400 con el código package_unavailable_for_provider y no abre ningún pago. GET /v1/billing/balance devuelve credits, el total que puedes gastar, dividido en permanent_credits, que no caducan, subscription_credits, que caducan en subscription_expires_at (una marca de tiempo en milisegundos, o null si no hay créditos de suscripción activos), y gift_credits, el regalo único de registro, que caducan en gift_expires_at (null si no hay regalo activo); el gasto usa primero los créditos de regalo, luego los de suscripción y por último los permanentes. Los planes de suscripción mensual aparecen por separado en plans dentro de GET /v1/billing/packages, cada uno con un id, un nombre, un precio mensual en usd y los créditos que concede en cada periodo. POST /v1/billing/subscribe recibe un plan_id de esa lista y devuelve la suscripción pendiente con un checkout_url al que enviar al pagador. Las suscripciones solo se pagan con tarjeta: un provider distinto de whop devuelve HTTP 400 con el código invalid_provider, y un plan_id desconocido devuelve invalid_plan. Cada periodo pagado sustituye los créditos de suscripción restantes por la cantidad completa del plan; los créditos de suscripción no usados no se acumulan y los créditos permanentes no se tocan. Suscribirte al plan que ya tienes devuelve HTTP 409 con already_subscribed. Pasar a un plan mayor lo inicia de inmediato y añade al nuevo periodo los créditos restantes del plan actual; pasar a uno menor devuelve HTTP 409 con downgrade_requires_cancel. GET /v1/billing/subscription devuelve la suscripción activa en subscription (plan_id, status, current_period_end y cancel_at_period_end) y un pago abierto en pending; cada campo es null si no existe. Solo puede haber un pago abierto a la vez: suscribirte de nuevo al mismo plan devuelve el pago abierto, elegir otro plan cierra antes el abierto y un pago que aún se está abriendo devuelve HTTP 409 con checkout_in_progress. POST /v1/billing/subscription/cancel detiene la renovación al final del periodo actual: los créditos de suscripción siguen disponibles hasta current_period_end y no se reembolsa nada. Devuelve la suscripción con cancel_at_period_end en true (llamarlo de nuevo devuelve lo mismo), HTTP 404 con subscription_not_found si no hay suscripción activa y HTTP 502 con subscription_cancel_failed si la cancelación no pudo confirmarse; en ese caso inténtalo de nuevo. Cada plan de plans lleva además un rank: un plan con rank mayor es una mejora respecto a uno con rank menor, así que lee la dirección en rank, no en el precio. GET /v1/billing/history lista los pagos de suscripción aparte, en subscription_payments (type subscription, payment_id, subscription_id, plan_id, amount_usd, status paid, refunded o mismatch, period_end y created_at), con su propia paginación mediante subscription_payments_offset y su total en subscription_payments_total.

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 eliminar una generación tú mismo: DELETE /v1/generations/{id} elimina de inmediato el archivo guardado y devuelve purged_at. Una generación eliminada desaparece de la API: ya no aparece en GET /v1/generations, y GET /v1/generations/{id}, el endpoint del archivo y un segundo DELETE devuelven HTTP 404 con el código not_found, igual que un id que nunca existió. Los créditos que costó no se reembolsan y siguen en GET /v1/billing/history. El registro de una generación fallida se elimina a los 30 días; a partir de ahí GET /v1/generations/{id} y el endpoint del archivo devuelven HTTP 404. 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.

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.