API reference

Send your API key as a Bearer token in the Authorization header on every request. Keys start with the vll_ prefix and are created on the API Keys page.

Authorization: Bearer vll_...

GET/v1/models

The valid models, sizes and resolutions with their credit costs. Read this endpoint instead of hardcoding a price list on your side. Every size carries ratio and tier alongside its label, so you never have to parse the label to know the aspect ratio or the resolution step, and every model carries max_prompt_length, the character limit this model enforces on prompt (and on any free-text parameter that does not declare its own).

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: integer 0–2147483647, random when omitted and echoed back · 1 credit for every size
• model: vellria-seedream5-pro · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (default: enabled) · 8 credits for every size
• model: vellria-seedream5-pro-edit · image to image · image_urls: 1–10 https URLs (required) · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (default: enabled) · 8 credits for every size + 1 credit for each reference image after the first
• model: vellria-qwen-3 · size: 1024*1024 | 1536*1024 | 1024*1536 | 2048*1152 | 1152*2048 | 2048*2048 · seed: integer 0–2147483647, random when omitted and echoed back · negative_prompt: text, at most 10000 characters · 5 credits for every size
• model: vellria-qwen-3-edit · image to image · image_urls: 1–3 https URLs (required) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: integer 0–2147483647, random when omitted and echoed back · negative_prompt: text, at most 10000 characters · 5 credits for every size + 1 credit for each reference image after the first
• model: vellria-qwenpro · size: 1024*1024 | 1536*1024 | 1024*1536 · seed: integer 0–2147483647, random when omitted and echoed back · negative_prompt: text, at most 10000 characters · 7 credits for every size
• model: vellria-qwenpro-edit · image to image · image_urls: 1–3 https URLs (required) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: integer 0–2147483647, random when omitted and echoed back · negative_prompt: text, at most 10000 characters · 7 credits for every size + 1 credit for each reference image after the first
• model: vellria-seedream5-lite · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 credits for every size
• model: vellria-seedream5-lite-edit · image to image · image_urls: 1–14 https URLs (required) · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 credits for every size
• model: vellria-wan26 · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1440*1440 | 1920*1080 | 1080*1920 · seed: integer 0–2147483647, random when omitted and echoed back · negative_prompt: text, at most 10000 characters · 6 credits for every size
• model: vellria-wan26-edit · image to image · image_urls: 1–4 https URLs (required) · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1664*936 | 936*1664 · seed: integer 0–2147483647, random when omitted and echoed back · negative_prompt: text, at most 10000 characters · 6 credits for every size

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

POST/v1/uploads

You do not have to host reference images yourself: send the file to this endpoint as a raw body, get a public URL back and use that URL in image_urls. The Content-Type header is required and must match the body; accepted types are image/jpeg, image/png, image/webp, image/bmp and image/gif, with a 20 MB limit per file. The URL carries an unguessable id and is kept for the same period as generated files; once it expires the endpoint returns HTTP 410 and content_expired.

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

GET/v1/generations/{id}

Generations run asynchronously; the status moves queued → processing → completed. Credits are refunded automatically when a generation fails.

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

GET/v1/projects

Folders group your generations and nothing else: they cost no credits and never touch a file. Create one with POST /v1/projects (a name of 1-64 characters, at most 100 folders per account), rename it with POST /v1/projects/{id} and remove it with DELETE /v1/projects/{id}. Deleting a folder never deletes generations: the rows stay and their project_id becomes null. Put a generation in a folder with POST /v1/generations/{id}/project, and take it out again by sending project_id: null to the same endpoint. To read them back, GET /v1/generations?project={id} returns one folder and GET /v1/generations?project=none returns the generations that are in no folder.

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-payment

Credits are topped up with crypto or with a card. GET /v1/billing/packages returns two package lists, crypto and card, because a package belongs to one payment method: crypto packages carry a bonus, card packages do not. Every package has an id, and buying one means sending that id as package_id; the price and the credits then come from the catalog and any price_amount in the same request is ignored. GET /v1/billing/currencies lists the coins enabled on the account and GET /v1/billing/min-amount the minimum for the selected coin; do not hardcode these values on your side. POST /v1/billing/create-payment takes either a crypto package_id or a free price_amount between 5 and 10000 USD, and returns a crypto payment address, the payin_extra_id field on networks that require a memo, and when the address expires; a free amount converts at the flat rate and carries no bonus, so the same dollars buy fewer credits than the matching package. POST /v1/billing/create-checkout opens a hosted card checkout instead and returns a checkout_url to send the payer to; it takes no pay_currency and no price_amount, only a card package_id, because every package is a separate product on the card provider. A package_id from the wrong list returns HTTP 400 with the invalid_package code. Both return the same payment record. Credits are added automatically once the payment confirms; you can poll the status with GET /v1/billing/payments/{id}.

curl https://vellria.com/v1/billing/create-payment \
  -H "Authorization: Bearer vll_..." \
  -H "Content-Type: application/json" \
  -d '{
    "package_id": "crypto_99",
    "pay_currency": "usdttrc20"
  }'

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

Generated files are kept for 14 days and then deleted from the server. The record stays in your billing history but the file becomes unreachable. The GET /v1/generations response carries a retention_days field and every generation carries expires_at; requesting an expired file returns HTTP 410 with the content_expired code. Download anything you need to keep for longer. You can also end the retention period early: DELETE /v1/generations/{id} removes the stored file straight away and stamps purged_at, exactly as the scheduled cleanup would. The generation row itself is never deleted, so the credits it cost stay visible in your history and are not refunded, and the file endpoint then answers with the same HTTP 410 and content_expired. Deleting twice is not an error and returns the same result; a generation that is still queued or processing cannot be deleted yet and returns HTTP 409 with the generation_in_progress code.

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

DELETE/v1/account

Closing your account deletes your generations and their stored files, your uploads, your API keys and your support messages, and signs you out. Any credits left on the account are lost and are not refunded. Payment records are kept as billing records, so a closed account still appears in the payment history we are required to retain. The endpoint is authenticated by session only: it is called from the Account page in the console, and a request carrying an API key is refused with HTTP 403. An account whose payment has not settled yet cannot be closed and returns HTTP 409 with the pending_payment code, because that payment can still be credited; the same 409 with merge_in_progress is returned while the account is being linked to another one. Wait a moment and try again in both cases.

20 images and 10 videos per minute. Exceeding the limit returns HTTP 429; wait for the period in the Retry-After header and try again.

Your prompt is not rewritten or softened on the way to the model: where a model ships a prompt rewriter as a setting, it is sent switched off. What remains is a narrow safety filter, and this is everything it covers.

• Depiction of minors and non-consensual content involving real people are refused with zero tolerance and result in permanent account closure.
• The provider running a model applies its own safety filter and can refuse a request after it has started; the generation is marked failed and the credits taken at the start are returned automatically.
• Nothing else is screened. Fictional adult content for adults runs as written, and the wording you submit is the wording the model receives.