Vellria API reference

Every entry carries id (the value you send as model), label, kind (image or video), family, and developer, the company that built it (null for a model offered under the Vellria name), plus two modes, text and reference: send only a prompt and the model runs in text mode — a text-to-image or text-to-video call; attach one or more reference images to that same id and it runs in reference mode instead — image-to-image or image-to-video — there is no separate id to pick between the two. Each mode carries its own sizes (image) or resolutions (video), a default, max_prompt_length (the character limit that mode enforces on prompt, and on any free-text parameter that does not declare its own), and parameters. Every size or resolution carries ratio and tier alongside its label, so you never have to parse the label to know the aspect ratio or the resolution step (a ratio of adaptive means the output takes its proportions from the input image). reference_images is null in text mode; in reference mode it carries the min and max reference images that mode accepts, extra_credits charged for each reference beyond the first, and the file limits a reference image must meet. A model whose reference slots carry fixed roles lists them in order under reference_images.roles (null for every model today): the first URL in image_urls would take the first role, each later URL the next one, and the last role would repeat for the rest.

The credits for the chosen size are taken when the generation starts and refunded automatically if it fails. Sizes, reference limits, parameters and prices for every model come from GET /v1/models.

It is priced like image to video on the same model, with no charge per reference. Errors, all HTTP 400 and before any credit is spent: invalid_reference_mode when the value is neither frame nor subject or the model has no subject mode, invalid_image_urls when subject mode gets no reference or more than the model accepts, and invalid_reference_token when the prompt cites an @image with no matching reference (@image3 with two images, for example). In frame mode @image1 is plain text.

It is OpenAI-compatible: point an OpenAI SDK at the Vellria base URL with your vll_ key. Each reply is charged per token from your credits.

Per 1M tokens: input 50 credits ($0.50) · cached input 5 credits ($0.05) · output 200 credits ($2.00).

• Replies are unfiltered: Vellria adds no content moderation to this endpoint, so you are responsible for moderating your own end users. A one-line identity instruction is placed before your messages; its tokens are not billed and are left out of usage.
• Images: add image_url parts to a user message, at most 4 per message and 8 per request. Upload the image with POST /v1/uploads first and pass the returned URL; data URLs are refused with data_url_not_supported.
• max_tokens defaults to 1024 and can be at most 4096. Reasoning or thinking fields are ignored and replies never contain reasoning.
• With stream: true the reply arrives as server-sent events (data: lines) in the OpenAI chunk format, ending with data: [DONE]. The chunk before it has empty choices and carries usage and the charge. An error after the stream has started arrives as a data: {"error": …} event; if text was already sent, that text is charged (the usage chunk comes just before the error), otherwise nothing is charged.
• Every reply carries OpenAI usage plus credits_charged (fractional credits), cost_usd and credits_debited (whole credits taken from the balance now; fractions add up on your account). Refused, failed or empty replies are not charged; a stream you cancel is charged for the tokens already produced.
• The balance must cover the longest possible reply before the request starts (402 insufficient_credits otherwise). Requests per minute and requests running at the same time are limited per account (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: "Let's start a story." }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

An image used as a reference must be a still JPEG, PNG, GIF or WebP of at most 20 MB, without transparent areas, and within the file caps the selected model publishes: `GET /v1/models` returns them per model under `reference_images.limits` (bytes, side length in pixels, megapixels). A reference outside those caps is refused with HTTP 400 and `image_unreadable`, reason `too_small` or `too_large`, before any credit is spent. Metadata such as EXIF is removed when the file is stored. The URL carries an unguessable id and is deleted 24 hours after upload if no generation uses it (the expires_at field of the response); once used as a reference in a generation it is kept until 48 hours after upload, much shorter than generated files; once it expires the endpoint returns HTTP 410 and content_expired. A generation's own file URL (/v1/generations/{id}/file) requires authentication and cannot be used as a reference: the generate endpoints reject it with HTTP 400 and the reference_not_public code before any credits are spent. Upload the file here instead, or turn an image generation into a public reference URL with POST /v1/generations/{id}/reference. Reference images are not screened for content: no picture is refused for who or what it shows, and there is no image_blocked refusal on this path. We refuse a reference only when the file itself cannot be read: an image that cannot be read returns HTTP 400 and image_unreadable, with reason animated, transparent too_small or too_large where that is the cause. The model itself may still decline a reference image it cannot process; that generation then fails with error_code reference_rejected and its credits are refunded automatically. If a reference cannot be prepared, the request returns HTTP 503 and reference_unavailable and no credits are spent. Prompts sent with an API key are passed to the model as sent; only requests involving the sexual abuse of minors are refused, with HTTP 400 and the content_blocked code. Every reference is first stored as an upload (an image given by an external URL is copied, without its metadata) and the provider fetches that same pinned URL, so the provider receives exactly the stored file.

The list at GET /v1/generations shows only completed and running generations: a failed generation is left out of the list and its total, while GET /v1/generations/{id} still returns it with its error_code for 30 days; after that the failed record is removed and GET /v1/generations/{id} and its file endpoint return HTTP 404 with the not_found code. Filtering the list with ?status=failed returns 400, and failed generations are also left out of the generations half of GET /v1/billing/history (generations_total included). Failures you have not been told about yet are listed by GET /v1/generations/failures: count, refunded_cents (credits actually refunded, 0 when no refund was made), until and up to 5 of the most recent in data. Mark them as seen with POST /v1/generations/failures/seen, sending either ids (1-50 generation ids) or until (every failure up to that timestamp); other accounts' ids are ignored and a failure is reported only once, on any device.

POST /v1/billing/create-checkout takes either a package_id from that list or a free price_amount in USD between 30 and 10000, rounded to cents; a free amount converts at the same flat rate as the packages. When both are sent, package_id wins and the price and credits come from the catalog. An unknown package_id returns HTTP 400 with the invalid_package code and an amount outside the range returns invalid_amount. At most five checkouts can be open at a time; another one returns HTTP 429 until one of them is paid, cancelled or expires. The response is the payment record with a checkout_url: send the payer there to pay in USD by card (Visa or Mastercard) on our payment partner's secure page. Credits are added automatically once the payment confirms; poll the status with GET /v1/billing/payments/{id}. POST /v1/billing/payments/{id}/cancel marks an open payment as cancelled; if it completes anyway, the credits are still added. The optional provider field picks the provider that takes the payment; the accepted values are whop (card), nowpayments (crypto) and telegram_stars (Telegram Stars). GET /v1/billing/packages lists the providers open for checkout in providers, and the first one is the default when the field is left out. An unknown or closed provider returns HTTP 400 with the invalid_provider code, and an empty providers list means payments are unavailable right now. Each package also lists in excluded_providers the providers that cannot take it, for example telegram_stars when the package is above the Telegram Stars invoice limit; a checkout for that package with an excluded provider returns HTTP 400 with the package_unavailable_for_provider code and opens no payment. GET /v1/billing/balance returns credits, the total you can spend, split into permanent_credits, which never expire, subscription_credits, which expire at subscription_expires_at (a millisecond timestamp, or null when no subscription credits are active), and gift_credits, the one-time signup gift, which expire at gift_expires_at (null when no gift is active); spending uses gift credits first, then subscription credits, then permanent credits. Monthly subscription plans are listed separately in plans on GET /v1/billing/packages, each with an id, a display name, a monthly usd price and the credits it grants every period. POST /v1/billing/subscribe takes a plan_id from that list and returns the pending subscription with a checkout_url to send the payer to. Subscriptions are paid by card only: a provider other than whop returns HTTP 400 with the invalid_provider code, and an unknown plan_id returns invalid_plan. Every paid period replaces the remaining subscription credits with the plan's full amount; unused subscription credits do not roll over, while permanent credits are never touched. Subscribing to the plan you already have returns HTTP 409 with already_subscribed. Moving up to a larger plan starts it at once and adds the remaining credits of the current plan to the new period; moving down returns HTTP 409 with downgrade_requires_cancel. GET /v1/billing/subscription returns the active subscription in subscription (plan_id, status, current_period_end and cancel_at_period_end) and an open checkout in pending; each is null when there is none. Only one checkout can be open at a time: subscribing again to the same plan returns the open checkout, choosing another plan closes the open one first, and a checkout still being opened returns HTTP 409 with checkout_in_progress. POST /v1/billing/subscription/cancel stops the renewal at the end of the current period: the subscription credits stay usable until current_period_end and nothing is refunded. It returns the subscription with cancel_at_period_end set to true (calling it again returns the same), HTTP 404 with subscription_not_found when there is no active subscription, and HTTP 502 with subscription_cancel_failed when the cancellation could not be confirmed; try again in that case. Each plan in plans also carries a rank: a plan with a higher rank is an upgrade over one with a lower rank, so read the direction from rank, not from the price. GET /v1/billing/history lists subscription payments separately in subscription_payments (type subscription, payment_id, subscription_id, plan_id, amount_usd, status paid, refunded or mismatch, period_end and created_at), paged on its own with subscription_payments_offset and counted in subscription_payments_total.

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 delete a generation yourself: DELETE /v1/generations/{id} removes the stored file straight away and returns purged_at. A deleted generation is gone from the API: it no longer appears in GET /v1/generations, and GET /v1/generations/{id}, its file endpoint and a second DELETE return HTTP 404 with the not_found code, the same as an id that never existed. The credits it cost are not refunded and stay in GET /v1/billing/history. The record of a failed generation is removed after 30 days; from then on GET /v1/generations/{id} and its file endpoint return HTTP 404. A generation that is still queued or processing cannot be deleted yet and returns HTTP 409 with the generation_in_progress code.

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.