Référence de l’API Vellria

Chaque entrée porte id (la valeur que vous envoyez comme model), label, kind (image ou video), family et developer, l’entreprise qui l’a conçu (null pour un modèle proposé sous le nom Vellria), ainsi que deux modes, text et reference : envoyez seulement un prompt et le modèle s’exécute en mode text — un appel text-to-image ou text-to-video ; joignez une ou plusieurs images de référence à ce même id et il s’exécute en mode reference à la place — image-to-image ou image-to-video —, il n’y a pas d’id distinct à choisir entre les deux. Chaque mode porte ses propres sizes (image) ou resolutions (vidéo), un default, max_prompt_length (la limite de caractères que ce mode applique au prompt, et à tout paramètre de texte libre qui ne déclare pas la sienne) et parameters. Chaque taille ou résolution porte ratio et tier en plus de son libellé : vous n’avez donc jamais à analyser le libellé pour connaître le format d’image ou le palier de résolution (un ratio adaptive signifie que le résultat reprend les proportions de l’image d’entrée). reference_images vaut null en mode text ; en mode reference, il porte le minimum et le maximum d’images de référence que ce mode accepte, extra_credits facturé pour chaque référence au-delà de la première, et les limites de fichier qu’une image de référence doit respecter. Un modèle dont les emplacements de référence ont des rôles fixes les liste dans l’ordre sous reference_images.roles (null pour tous les modèles à ce jour) : la première URL de image_urls prendrait le premier rôle, chaque URL suivante le suivant, et le dernier rôle se répéterait pour le reste.

Les crédits de la taille choisie sont débités au démarrage de la génération et remboursés automatiquement si elle échoue. Les tailles, les limites de référence, les paramètres et les prix de chaque modèle viennent de GET /v1/models.

Le mode subject n'existe que sur les modèles dont l'entrée GET /v1/models comporte un bloc subject (null pour les autres) ; ce bloc indique ses propres résolutions, durées, formats et paramètres, la limite de références dans subject.reference_images.max et le modèle du jeton dans subject.reference_token. Il est facturé comme l'image en vidéo sur le même modèle, sans supplément par référence. Erreurs, toutes en HTTP 400 et avant tout débit de crédits : invalid_reference_mode si la valeur n'est ni frame ni subject ou si le modèle n'a pas de mode subject ; invalid_image_urls si le mode subject ne reçoit aucune référence ou plus que le modèle n'en accepte ; invalid_reference_token si le prompt cite un @image sans référence correspondante (par exemple @image3 avec deux images). En mode frame, @image1 est du texte ordinaire.

Il est compatible OpenAI : pointez n'importe quel SDK OpenAI vers l'URL de base de Vellria avec votre clé vll_. Chaque réponse est facturée au token sur vos crédits.

Par million de tokens : entrée 50 crédits (0,50 $US) · entrée en cache 5 crédits (0,05 $US) · sortie 200 crédits (2,00 $US).

• Les réponses ne sont pas filtrées : Vellria n'ajoute aucune modération de contenu à cet endpoint, la modération de vos propres utilisateurs finaux vous incombe. Une instruction d'identité d'une ligne est placée avant vos messages ; ses tokens ne sont pas facturés et ne comptent pas dans usage.
• Images : ajoutez des parties image_url à un message user, au plus 4 par message et 8 par requête. Importez d'abord l'image avec POST /v1/uploads et passez l'URL renvoyée ; les data URL sont refusées avec data_url_not_supported.
• max_tokens vaut 1024 par défaut et au plus 4096. Les champs de raisonnement (reasoning, thinking) sont ignorés et les réponses ne contiennent jamais de raisonnement.
• Avec stream: true la réponse arrive en événements serveur (lignes data:) au format de fragments OpenAI et se termine par data: [DONE]. Le fragment précédent a un choices vide et porte usage et la facturation. Une erreur après le début du streaming arrive sous forme d'événement data: {"error": …} ; si du texte a déjà été envoyé, ce texte est facturé (le fragment usage arrive juste avant l'erreur), sinon rien n'est facturé.
• Chaque réponse porte usage d'OpenAI ainsi que credits_charged (crédits fractionnaires), cost_usd et credits_debited (crédits entiers débités du solde maintenant ; les fractions s'accumulent sur votre compte). Les réponses refusées, échouées ou vides ne sont pas facturées ; un streaming que vous annulez est facturé pour les tokens déjà produits.
• Le solde doit couvrir la réponse la plus longue possible avant le début de la requête (sinon 402 insufficient_credits). Les requêtes par minute et les requêtes simultanées sont limitées par compte (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: "Commençons une histoire." }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

Une image utilisée comme référence doit être une image fixe au format JPEG, PNG, GIF ou WebP de 20 Mo au maximum, sans zone transparente. Une fois ce plafond passé, chaque modèle publie les limites qu’il accepte : `GET /v1/models` les renvoie par modèle sous `reference_images.limits` (octets, côté en pixels, mégapixels). Une référence hors de ces limites est refusée avec HTTP 400 et `image_unreadable`, motif `too_small` ou `too_large`, avant toute dépense de crédits. Les métadonnées (EXIF, par exemple) sont supprimées à l’enregistrement du fichier. L’URL contient un identifiant impossible à deviner et est supprimée 24 heures après l’envoi si aucune génération ne l’utilise (champ expires_at de la réponse) ; utilisée comme référence dans une génération, elle reste disponible 48 heures après l’envoi, bien moins longtemps que les fichiers générés ; une fois ce délai écoulé, l’endpoint renvoie HTTP 410 et content_expired. L’URL du fichier d’une génération (/v1/generations/{id}/file) exige une authentification et ne peut pas servir de référence : les endpoints de génération la refusent avec HTTP 400 et le code reference_not_public avant tout débit de crédits. Importez plutôt le fichier ici, ou transformez une génération d’image en URL de référence publique avec POST /v1/generations/{id}/reference. Les images de référence ne sont soumises à aucun contrôle de contenu : aucune image n’est refusée pour les personnes ou les choses qu’elle montre, et il n’existe aucun refus image_blocked sur ce chemin. Nous ne refusons une référence que lorsque le fichier lui-même est illisible : une image illisible renvoie HTTP 400 et image_unreadable, et reason vaut animated, transparent too_small ou too_large lorsque c’est la cause. Le modèle lui-même peut encore refuser une image de référence qu’il ne parvient pas à traiter ; cette génération échoue alors avec error_code reference_rejected et ses crédits sont remboursés automatiquement. Si une référence ne peut pas être préparée, la requête renvoie HTTP 503 et reference_unavailable, sans débit de crédits. Les prompts envoyés avec une clé d’API arrivent au modèle tels quels ; seules les requêtes impliquant des abus sexuels sur mineurs sont refusées, avec HTTP 400 et le code content_blocked. Chaque référence est d’abord enregistrée comme fichier importé (une image fournie par une URL externe est copiée, sans ses métadonnées), et le prestataire récupère cette même URL figée : il reçoit donc exactement le fichier enregistré.

La liste GET /v1/generations ne montre que les générations terminées et en cours : une génération en échec n’apparaît ni dans la liste ni dans son total, tandis que GET /v1/generations/{id} la renvoie avec son error_code pendant 30 jours ; ensuite l’enregistrement en échec est supprimé et GET /v1/generations/{id} comme l’endpoint du fichier renvoient HTTP 404 avec le code not_found. Filtrer la liste avec ?status=failed renvoie 400, et les générations en échec sont aussi exclues de la moitié générations de GET /v1/billing/history (generations_total compris). Les échecs qui ne vous ont pas encore été signalés sont listés par GET /v1/generations/failures : count, refunded_cents (crédits réellement remboursés, 0 sans remboursement), until et jusqu'à 5 des plus récents dans data. Marquez-les comme vus avec POST /v1/generations/failures/seen en envoyant soit ids (1 à 50 identifiants de génération), soit until (tous les échecs jusqu'à cet horodatage) ; les identifiants d'autres comptes sont ignorés et un échec n'est signalé qu'une fois, quel que soit l'appareil.

POST /v1/billing/create-checkout accepte soit un package_id de cette liste, soit un price_amount libre en USD entre 30 et 10000, arrondi au centime ; un montant libre est converti au même taux fixe que les packs. Si les deux sont envoyés, package_id l’emporte et le prix comme les crédits proviennent du catalogue. Un package_id inconnu renvoie HTTP 400 avec le code invalid_package, et un montant hors limites renvoie invalid_amount. Cinq paiements au maximum peuvent être ouverts en même temps ; au-delà, la requête renvoie HTTP 429 jusqu’à ce que l’un d’eux soit payé, annulé ou expiré. La réponse est l’enregistrement du paiement, avec un checkout_url : redirigez le payeur vers cette adresse pour qu’il paie en USD par carte (Visa ou Mastercard) sur la page sécurisée de notre partenaire de paiement. Les crédits sont ajoutés automatiquement dès que le paiement est confirmé ; suivez son statut avec GET /v1/billing/payments/{id}. POST /v1/billing/payments/{id}/cancel marque un paiement ouvert comme annulé ; s’il aboutit malgré tout, les crédits sont tout de même ajoutés. Le champ facultatif provider choisit le prestataire qui encaisse le paiement ; les valeurs acceptées sont whop (carte), nowpayments (crypto) et telegram_stars (Étoiles Telegram). GET /v1/billing/packages liste dans providers les prestataires ouverts au checkout, et le premier est utilisé par défaut si le champ est omis. Un prestataire inconnu ou fermé renvoie HTTP 400 avec le code invalid_provider, et une liste providers vide signifie que les paiements sont indisponibles pour le moment. Chaque pack indique aussi dans excluded_providers les prestataires qui ne peuvent pas l’encaisser, par exemple telegram_stars quand le pack dépasse la limite de facture des Étoiles Telegram ; un checkout de ce pack avec un prestataire exclu renvoie HTTP 400 avec le code package_unavailable_for_provider et n’ouvre aucun paiement. GET /v1/billing/balance renvoie credits, le total dépensable, réparti entre permanent_credits, qui n'expirent jamais, subscription_credits, qui expirent à subscription_expires_at (un horodatage en millisecondes, ou null s'il n'y a pas de crédits d'abonnement actifs), et gift_credits, le cadeau unique d'inscription, qui expirent à gift_expires_at (null s'il n'y a pas de cadeau actif) ; les dépenses utilisent d'abord les crédits offerts, puis les crédits d'abonnement, puis les crédits permanents. Les formules d'abonnement mensuel sont listées à part dans plans de GET /v1/billing/packages, chacune avec un id, un nom, un prix mensuel en usd et les crédits accordés à chaque période. POST /v1/billing/subscribe prend un plan_id de cette liste et renvoie l'abonnement en attente avec un checkout_url vers lequel envoyer le payeur. Les abonnements se paient uniquement par carte : un provider autre que whop renvoie HTTP 400 avec le code invalid_provider, et un plan_id inconnu renvoie invalid_plan. Chaque période payée remplace les crédits d'abonnement restants par le montant complet de la formule ; les crédits d'abonnement non utilisés ne sont pas reportés et les crédits permanents ne sont pas touchés. S'abonner à la formule que vous avez déjà renvoie HTTP 409 avec already_subscribed. Passer à une formule supérieure la démarre immédiatement et ajoute les crédits restants de la formule actuelle à la nouvelle période ; passer à une formule inférieure renvoie HTTP 409 avec downgrade_requires_cancel. GET /v1/billing/subscription renvoie l'abonnement actif dans subscription (plan_id, status, current_period_end et cancel_at_period_end) et un paiement ouvert dans pending ; chaque champ vaut null s'il n'existe pas. Un seul paiement peut être ouvert à la fois : se réabonner à la même formule renvoie le paiement ouvert, choisir une autre formule ferme d'abord celui qui est ouvert, et un paiement encore en cours d'ouverture renvoie HTTP 409 avec checkout_in_progress. POST /v1/billing/subscription/cancel arrête le renouvellement à la fin de la période en cours : les crédits d'abonnement restent utilisables jusqu'à current_period_end et rien n'est remboursé. Il renvoie l'abonnement avec cancel_at_period_end à true (un nouvel appel renvoie la même chose), HTTP 404 avec subscription_not_found s'il n'y a pas d'abonnement actif et HTTP 502 avec subscription_cancel_failed si l'annulation n'a pas pu être confirmée ; réessayez dans ce cas. Chaque plan de plans porte aussi un rank : un plan de rank plus élevé est une montée en gamme par rapport à un plan de rank plus bas ; lisez le sens dans rank, pas dans le prix. GET /v1/billing/history liste les paiements d’abonnement à part, dans subscription_payments (type subscription, payment_id, subscription_id, plan_id, amount_usd, status paid, refunded ou mismatch, period_end et created_at), paginés séparément avec subscription_payments_offset et comptés dans subscription_payments_total.

La réponse de GET /v1/generations porte un champ retention_days et chaque génération porte expires_at ; demander un fichier expiré renvoie HTTP 410 avec le code content_expired. Téléchargez tout ce que vous devez garder plus longtemps. Vous pouvez aussi supprimer une génération vous-même : DELETE /v1/generations/{id} supprime immédiatement le fichier stocké et renvoie purged_at. Une génération supprimée disparaît de l’API : elle n’apparaît plus dans GET /v1/generations, et GET /v1/generations/{id}, l’endpoint du fichier et un second DELETE renvoient HTTP 404 avec le code not_found, comme un id qui n’a jamais existé. Les crédits qu’elle a coûtés ne sont pas remboursés et restent dans GET /v1/billing/history. L’enregistrement d’une génération en échec est supprimé au bout de 30 jours ; ensuite GET /v1/generations/{id} et l’endpoint du fichier renvoient HTTP 404. Une génération encore queued ou processing ne peut pas encore être supprimée et renvoie HTTP 409 avec le code generation_in_progress.

Les données de paiement sont conservées à titre de justificatifs de facturation : un compte fermé figure donc toujours dans l’historique des paiements que nous sommes tenus de conserver. L’endpoint s’authentifie uniquement par session : il est appelé depuis la page Compte de la Console, et une requête portant une clé API est refusée avec HTTP 403. Un compte dont un paiement n’a pas encore abouti ne peut pas être fermé et renvoie HTTP 409 avec le code pending_payment, car ce paiement peut encore être crédité ; le même 409 avec merge_in_progress est renvoyé pendant que le compte est en cours de liaison avec un autre compte. Dans les deux cas, patientez un instant, puis réessayez.