Référence de l’API Vellria

Envoyez votre clé API comme jeton Bearer dans l’en-tête Authorization de chaque requête. Les clés commencent par le préfixe vll_ et se créent sur la page Clés API.

Authorization: Bearer vll_...

GET/v1/models

Les modèles, tailles et résolutions valides, avec leur coût en crédits. Interrogez cet endpoint plutôt que de coder en dur une grille tarifaire de votre côté. Chaque taille 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). Chaque modèle porte aussi max_prompt_length, la limite de caractères que ce modèle applique au prompt (et à tout paramètre de texte libre qui ne déclare pas la sienne), ainsi que developer, l’entreprise qui l’a conçu (null pour un modèle proposé sous le nom 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: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · 1 crédit quelle que soit la taille
• model: vellria-seedream5-pro · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (par défaut : enabled) · 8 crédits quelle que soit la taille
• model: vellria-seedream5-pro-edit · image en image · image_urls: 1–10 URL https (obligatoire) · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (par défaut : enabled) · 8 crédits quelle que soit la taille + 1 crédit par image de référence au-delà de la première
• model: vellria-qwen-3-image · size: 1024*1024 | 1536*1024 | 1024*1536 | 2048*1152 | 1152*2048 | 2048*2048 · seed: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · negative_prompt: texte, 10000 caractères au maximum · 5 crédits quelle que soit la taille
• model: vellria-qwen-3-image-edit · image en image · image_urls: 1–3 URL https (obligatoire) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · negative_prompt: texte, 10000 caractères au maximum · 5 crédits quelle que soit la taille + 1 crédit par image de référence au-delà de la première
• model: vellria-qwen-3-pro-image · size: 1024*1024 | 1536*1024 | 1024*1536 · seed: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · negative_prompt: texte, 10000 caractères au maximum · 7 crédits quelle que soit la taille
• model: vellria-qwen-3-pro-edit · image en image · image_urls: 1–3 URL https (obligatoire) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · negative_prompt: texte, 10000 caractères au maximum · 7 crédits quelle que soit la taille + 1 crédit par image de référence au-delà de la première
• model: vellria-seedream5-lite · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 crédits quelle que soit la taille
• model: vellria-seedream5-lite-edit · image en image · image_urls: 1–14 URL https (obligatoire) · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 crédits quelle que soit la taille
• model: vellria-wan26-image · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1440*1440 | 1920*1080 | 1080*1920 · seed: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · negative_prompt: texte, 10000 caractères au maximum · 6 crédits quelle que soit la taille
• model: vellria-wan26-image-edit · image en image · image_urls: 1–4 URL https (obligatoire) · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1664*936 | 936*1664 · seed: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · negative_prompt: texte, 10000 caractères au maximum · 6 crédits quelle que soit la taille
• model: vellria-wan27-image-edit · image en image · image_urls: 1–9 URL https (obligatoire) · size: 2K · seed: entier 0–2147483647, aléatoire s’il est omis, puis renvoyé dans la réponse · 6 crédits quelle que soit la taille

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 secondes · resolution: 480p | 720p | 1080p · 480p 28 · 720p 60 · 1080p 120 crédits/s
• model: vellria-seedance-2-5-image-video · image en vidéo · image_urls: 1–1 URL https (obligatoire) · duration: 4–30 secondes · resolution: 480p | 720p | 1080p · 480p 28 · 720p 60 · 1080p 120 crédits/s
• model: vellria-seedance-2-0-fast-video · duration: 4–15 secondes · 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édits/s
• model: vellria-seedance-2-0-fast-image-video · image en vidéo · image_urls: 1–1 URL https (obligatoire) · duration: 4–15 secondes · 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édits/s
• model: vellria-minimax-h3-video · duration: 4–15 secondes · 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édits/s
• model: vellria-minimax-h3-image-video · image en vidéo · image_urls: 1–1 URL https (obligatoire) · duration: 4–15 secondes · resolution: 480P | 768P | 1440p-sr | 4k-sr · 480P 5 · 768P 7 · 1440p-sr 12 · 4k-sr 16 crédits/s
• model: vellria-minimax-h3-max-video · duration: 5–15 secondes · 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édits/s
• model: vellria-minimax-h3-max-image-video · image en vidéo · image_urls: 1–1 URL https (obligatoire) · duration: 5–15 secondes · resolution: 480P | 768P | 1440p-sr | 4k-sr · 480P 8 · 768P 15 · 1440p-sr 30 · 4k-sr 50 crédits/s
• model: vellria-happyhorse-1-1-video · duration: 3–15 secondes · 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édits/s
• model: vellria-happyhorse-1-1-image-video · image en vidéo · image_urls: 1–1 URL https (obligatoire) · duration: 3–15 secondes · resolution: 480p | 720p | 1080p · 480p 11 · 720p 22 · 1080p 29 crédits/s
• model: vellria-wan-3-video · duration: 2–30 secondes · resolution: 480p | 720p | 1080p · ratio: adaptive | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480p 8 · 720p 16 · 1080p 32 crédits/s
• model: vellria-wan-3-image-video · image en vidéo · image_urls: 1–1 URL https (obligatoire) · duration: 2–30 secondes · resolution: 480p | 720p | 1080p · 480p 8 · 720p 16 · 1080p 32 crédits/s
• model: vellria-wan-3-pro-video · duration: 2–30 secondes · resolution: 480p | 720p | 1080p · ratio: adaptive | 16:9 | 4:3 | 1:1 | 3:4 | 9:16 · 480p 11 · 720p 22 · 1080p 45 crédits/s
• model: vellria-wan-3-pro-image-video · image en vidéo · image_urls: 1–1 URL https (obligatoire) · duration: 2–30 secondes · resolution: 480p | 720p | 1080p · 480p 11 · 720p 22 · 1080p 45 crédits/s

POST/v1/uploads

Vous n’avez pas à héberger vous-même les images de référence : envoyez le fichier à cet endpoint en corps brut, récupérez une URL publique et utilisez-la dans image_urls. L’en-tête Content-Type est obligatoire et doit correspondre au corps ; les types acceptés sont image/jpeg, image/png, image/webp, image/bmp et image/gif, avec une limite de 20 Mo par fichier. 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. Les métadonnées (EXIF, par exemple) sont supprimées à l’enregistrement du fichier. L’URL contient un identifiant impossible à deviner et reste disponible aussi 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 envoyées à POST /v1/generate/image ou POST /v1/generate/video sont contrôlées automatiquement, l’une après l’autre, avant tout débit de crédits : toutes les personnes représentées doivent être majeures (les images sans personne sont acceptées), une image montrant une personnalité réelle connue est refusée, de même qu’une image portant un texte destiné au contrôle, comme des instructions ou des affirmations sur l’âge. Une requête refusée renvoie HTTP 400 avec le code image_blocked et un motif dans reason (minor, public_figure ou image_text), sans préciser l’image concernée ; une image illisible renvoie HTTP 400 et image_unreadable, et reason vaut animated, transparent ou too_large lorsque c’est la cause. 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 contrôle comme le prestataire récupèrent cette même URL : le prestataire reçoit donc exactement le fichier contrôlé. Si le contrôle est indisponible, la requête renvoie HTTP 503 et moderation_unavailable, et rien n’est facturé : les générations avec images de référence dépendent donc de la disponibilité du contrôle. Les générations sans image de référence ne sont pas contrôlées de cette manière.

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

GET/v1/generations/{id}

Les générations s’exécutent de manière asynchrone ; le statut passe par queued → processing → completed (en file d’attente → en cours → terminé). Les crédits sont remboursés automatiquement lorsqu’une génération échoue.

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

GET/v1/projects

Les dossiers regroupent vos générations, rien de plus : ils ne coûtent aucun crédit et ne touchent jamais à un fichier. Créez-en un avec POST /v1/projects (un nom de 1 à 64 caractères, 100 dossiers au maximum par compte), renommez-le avec POST /v1/projects/{id} et supprimez-le avec DELETE /v1/projects/{id}. Supprimer un dossier ne supprime jamais de génération : les lignes restent et leur project_id devient null. Pour placer une génération dans un dossier, utilisez POST /v1/generations/{id}/project ; pour l’en retirer, envoyez project_id: null au même endpoint. Pour les retrouver, GET /v1/generations?project={id} renvoie un dossier et GET /v1/generations?project=none renvoie les générations qui ne sont dans aucun dossier. La liste est paginée avec limit (1–50, 20 par défaut) et offset ; chaque page porte has_more et total, le nombre de générations correspondant aux mêmes filtres.

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

Les crédits s’achètent sur une page de paiement hébergée. GET /v1/billing/packages renvoie une liste unique de packs, chacun avec un id, un prix usd et ses crédits, ainsi que min_usd et max_usd pour un montant libre ; récupérez ces valeurs depuis l’endpoint plutôt que de les coder en dur. POST /v1/billing/create-checkout accepte soit un package_id de cette liste, soit un price_amount libre en USD entre 20 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 finalise le paiement sur la page sécurisée de notre partenaire de paiement, où les moyens de paiement proposés dépendent du pays du payeur. 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.

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 }'

Les fichiers générés sont conservés 14 jours, puis supprimés du serveur. L’enregistrement reste dans votre historique de facturation, mais le fichier devient inaccessible. 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 mettre fin à la conservation plus tôt : DELETE /v1/generations/{id} supprime immédiatement le fichier stocké et renseigne purged_at, exactement comme le nettoyage planifié. La ligne de la génération elle-même n’est jamais supprimée : les crédits qu’elle a coûtés restent visibles dans votre historique et ne sont pas remboursés, et l’endpoint du fichier répond ensuite avec le même HTTP 410 et content_expired. Supprimer deux fois n’est pas une erreur et renvoie le même résultat ; 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.

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

DELETE/v1/account

Fermer votre compte supprime vos générations et leurs fichiers stockés, vos fichiers importés, vos clés API et vos messages d’assistance, puis vous déconnecte. Les crédits restant sur le compte sont perdus et ne sont pas remboursés. 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.

20 images et 10 vidéos par minute. Les générations avec images de référence partagent aussi une limite de 120 tentatives par heure, refus compris ; au-delà, les endpoints de génération renvoient le code reference_rate_limited. Le dépassement d’une limite renvoie HTTP 429 ; attendez la durée indiquée dans l’en-tête Retry-After, puis réessayez.

Votre prompt n’est ni réécrit ni adouci avant d’arriver au modèle : lorsqu’un modèle propose la réécriture du prompt comme réglage, ce réglage est envoyé désactivé. Il reste un filtre de sécurité étroit et une courte liste de règles ; tout est ci-dessous.

• Un contrôle automatique examine le texte du prompt avant tout débit de crédits et refuse ce qu’il reconnaît dans une liste fixe de catégories : contenu sexuel impliquant un mineur, zoophilie, inceste entre parents par le sang, relations sexuelles non consenties, violence extrême et gore, contenu en caméra cachée ou voyeuriste, ainsi qu’une demande d’échange de visage (face swap) ou de deepfake, ou un prompt nommant une personnalité réelle connue ; l’interdiction elle-même est plus large que ce que ce contrôle détecte. Les images de référence sont contrôlées automatiquement de la même manière avant tout débit de crédits : une image montrant une personne pouvant avoir moins de 21 ans ou une personnalité réelle connue est refusée, de même qu’une image portant un texte destiné au contrôle. Une personne réelle ordinaire, non célèbre, n’est identifiée par aucun des deux contrôles ; la représenter sans son consentement est interdit par les conditions d’utilisation, mais n’est pas détecté automatiquement. La règle sur les mineurs comme celle sur l’absence de consentement relèvent de la tolérance zéro ; selon les conditions d’utilisation, toute infraction entraîne la fermeture du compte sans préavis.
• Le prestataire qui exécute un modèle applique son propre filtre de sécurité et peut refuser une requête après son démarrage ; la génération est alors marquée comme échouée et les crédits débités au départ sont remboursés automatiquement.