Referência da API da Vellria

Cada entrada traz id (o valor que você envia como model), label, kind (image ou video), family e developer, a empresa que o criou (null para um modelo oferecido com o nome Vellria), além de dois modos, text e reference: envie apenas um prompt e o modelo é executado no modo text — uma chamada text-to-image ou text-to-video; anexe uma ou mais imagens de referência a esse mesmo id e ele é executado no modo reference em vez disso — image-to-image ou image-to-video —, não há um id separado para escolher entre os dois. Cada modo traz seus próprios sizes (imagem) ou resolutions (vídeo), um default, max_prompt_length (o limite de caracteres que esse modo impõe ao prompt, e a qualquer parâmetro de texto livre que não declare o próprio limite) e parameters. Cada tamanho ou resolução traz ratio e tier junto com o rótulo, então você nunca precisa interpretar o rótulo para saber a proporção ou o nível de resolução (um ratio adaptive significa que o resultado usa as proporções da imagem de entrada). reference_images é null no modo text; no modo reference ele traz o mínimo e o máximo de imagens de referência que esse modo aceita, extra_credits cobrado por cada referência após a primeira, e os limites de arquivo que uma imagem de referência deve cumprir. Um modelo cujos espaços de referência têm papéis fixos os lista em ordem em reference_images.roles (null em todos os modelos por ora): a primeira URL de image_urls receberia o primeiro papel, cada URL seguinte o próximo, e o último papel se repetiria para o restante.

Os créditos do tamanho escolhido são cobrados quando a geração começa e reembolsados automaticamente se ela falhar. Tamanhos, limites de referência, parâmetros e preços de cada modelo vêm de GET /v1/models.

O modo subject só existe nos modelos cuja entrada em GET /v1/models traz um bloco subject (null nos demais); esse bloco informa as próprias resoluções, durações, proporções e parâmetros, o limite de referências em subject.reference_images.max e o padrão do token em subject.reference_token. O preço é o mesmo de imagem em vídeo no mesmo modelo, sem cobrança por referência. Erros, todos HTTP 400 e antes de qualquer crédito ser gasto: invalid_reference_mode quando o valor não é frame nem subject ou o modelo não tem modo subject; invalid_image_urls quando o modo subject não recebe referência ou recebe mais do que o modelo aceita; invalid_reference_token quando o prompt cita um @image sem referência correspondente (por exemplo, @image3 com duas imagens). No modo frame, @image1 é texto comum.

É compatível com a OpenAI: aponte qualquer SDK da OpenAI para a URL base da Vellria com sua chave vll_. Cada resposta é cobrada por token dos seus créditos.

Por 1M de tokens: entrada 50 créditos (US$ 0,50) · entrada em cache 5 créditos (US$ 0,05) · saída 200 créditos (US$ 2,00).

• As respostas não têm filtro: a Vellria não adiciona moderação de conteúdo a este endpoint, então moderar seus próprios usuários finais é responsabilidade sua. Uma instrução de identidade de uma linha é colocada antes das suas mensagens; os tokens dela não são cobrados e não entram em usage.
• Imagens: adicione partes image_url a uma mensagem user, no máximo 4 por mensagem e 8 por solicitação. Envie a imagem antes com POST /v1/uploads e passe a URL devolvida; data URLs são recusadas com data_url_not_supported.
• max_tokens vale 1024 por padrão e no máximo 4096. Campos de raciocínio (reasoning, thinking) são ignorados e as respostas nunca contêm raciocínio.
• Com stream: true a resposta chega como eventos do servidor (linhas data:) no formato de fragmentos da OpenAI e termina com data: [DONE]. O fragmento anterior tem choices vazio e traz usage e a cobrança. Um erro depois do início do streaming chega como evento data: {"error": …}; se já foi enviado texto, esse texto é cobrado (o fragmento com usage chega logo antes do erro), senão nada é cobrado.
• Cada resposta traz usage da OpenAI mais credits_charged (créditos fracionários), cost_usd e credits_debited (créditos inteiros descontados do saldo agora; as frações se acumulam na sua conta). Respostas recusadas, com falha ou vazias não são cobradas; um streaming que você cancela é cobrado pelos tokens já gerados.
• O saldo precisa cobrir a resposta mais longa possível antes de a solicitação começar (senão 402 insufficient_credits). Solicitações por minuto e solicitações simultâneas são limitadas por conta (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: "Vamos começar uma história." }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

Uma imagem usada como referência deve ser um JPEG, PNG, GIF ou WebP estático de até 20 MB, sem áreas transparentes e dentro dos limites de arquivo que o modelo escolhido publica: `GET /v1/models` os devolve por modelo em `reference_images.limits` (bytes, lado em pixels e megapixels). Uma referência fora desses limites é recusada com HTTP 400 e `image_unreadable`, com motivo `too_small` ou `too_large`, antes de gastar créditos. Metadados como EXIF são removidos quando o arquivo é armazenado. A URL traz um ID impossível de adivinhar e é excluída 24 horas após o envio se nenhuma geração a usar (campo expires_at da resposta); se for usada como referência em uma geração, fica armazenada por 48 horas após o envio, bem menos que os arquivos gerados; depois que ela expira, o endpoint retorna HTTP 410 e content_expired. A URL do arquivo de uma geração (/v1/generations/{id}/file) exige autenticação e não pode ser usada como referência: os endpoints de geração a rejeitam com HTTP 400 e o código reference_not_public antes de qualquer crédito ser gasto. Em vez disso, envie o arquivo aqui ou transforme uma geração de imagem em uma URL de referência pública com POST /v1/generations/{id}/reference. As imagens de referência não passam por verificação de conteúdo: nenhuma imagem é recusada por quem ou o que mostra, e não há recusa image_blocked nesta rota. Nós só recusamos uma referência quando o próprio arquivo não pode ser lido: uma imagem que não pode ser lida retorna HTTP 400 e image_unreadable, com reason animated, transparent too_small ou too_large quando essa for a causa. O próprio modelo ainda pode recusar uma imagem de referência que não consegue processar; essa geração falha com error_code reference_rejected e os créditos são reembolsados automaticamente. Se uma referência não puder ser preparada, a requisição retorna HTTP 503 e reference_unavailable, sem gastar créditos. Prompts enviados com uma chave de API chegam ao modelo como foram enviados; só são recusadas as requisições que envolvem abuso sexual de menores, com HTTP 400 e o código content_blocked. Toda referência é primeiro armazenada como arquivo enviado (uma imagem informada por URL externa é copiada, sem os metadados) e o provedor do modelo busca essa mesma URL fixada, então o provedor recebe exatamente o arquivo armazenado.

A lista de GET /v1/generations mostra apenas gerações concluídas e em andamento: uma geração que falhou fica fora da lista e do seu total, enquanto GET /v1/generations/{id} continua a devolvê-la com o seu error_code por 30 dias; depois o registro que falhou é excluído e GET /v1/generations/{id} e o endpoint do arquivo devolvem HTTP 404 com o código not_found. Filtrar a lista com ?status=failed devolve 400, e as gerações que falharam também ficam fora da metade de gerações de GET /v1/billing/history (incluindo generations_total). As falhas que ainda não foram informadas a você são listadas por GET /v1/generations/failures: count, refunded_cents (créditos realmente reembolsados, 0 quando não houve reembolso), until e até 5 das mais recentes em data. Marque-as como vistas com POST /v1/generations/failures/seen enviando ids (1 a 50 ids de geração) ou until (todas as falhas até esse instante); ids de outras contas são ignorados e uma falha é informada só uma vez, em qualquer dispositivo.

POST /v1/billing/create-checkout recebe um package_id dessa lista ou um price_amount livre em USD entre 30 e 10000, arredondado para centavos; um valor livre é convertido pela mesma tarifa fixa dos pacotes. Quando os dois são enviados, package_id prevalece e o preço e os créditos vêm do catálogo. Um package_id desconhecido retorna HTTP 400 com o código invalid_package, e um valor fora do intervalo retorna invalid_amount. No máximo cinco pagamentos podem ficar abertos ao mesmo tempo; um novo retorna HTTP 429 até que um deles seja pago, cancelado ou expire. A resposta é o registro do pagamento com um checkout_url: envie o pagador para esse endereço para pagar em USD com cartão (Visa ou Mastercard) na página segura do nosso parceiro de pagamento. Os créditos são adicionados automaticamente assim que o pagamento é confirmado; consulte o status com GET /v1/billing/payments/{id}. POST /v1/billing/payments/{id}/cancel marca um pagamento aberto como cancelado; se ele for concluído mesmo assim, os créditos ainda são adicionados. O campo opcional provider escolhe o provedor que recebe o pagamento; os valores aceitos são whop (cartão), nowpayments (cripto) e telegram_stars (Estrelas do Telegram). GET /v1/billing/packages lista em providers os provedores abertos para checkout, e o primeiro é o padrão quando o campo não é enviado. Um provedor desconhecido ou fechado retorna HTTP 400 com o código invalid_provider, e uma lista providers vazia significa que os pagamentos estão indisponíveis no momento. Cada pacote também lista em excluded_providers os provedores que não podem recebê-lo, por exemplo telegram_stars quando o pacote passa do limite de fatura do Telegram Stars; um checkout desse pacote com um provedor excluído retorna HTTP 400 com o código package_unavailable_for_provider e não abre nenhum pagamento. GET /v1/billing/balance devolve credits, o total que você pode gastar, dividido em permanent_credits, que não expiram, subscription_credits, que expiram em subscription_expires_at (um carimbo de data em milissegundos, ou null quando não há créditos de assinatura ativos), e gift_credits, o presente único de cadastro, que expiram em gift_expires_at (null quando não há presente ativo); os gastos usam primeiro os créditos de presente, depois os de assinatura e por último os permanentes. Os planos de assinatura mensal aparecem separadamente em plans no GET /v1/billing/packages, cada um com um id, um nome, um preço mensal em usd e os créditos concedidos a cada período. POST /v1/billing/subscribe recebe um plan_id dessa lista e devolve a assinatura pendente com um checkout_url para onde enviar o pagador. As assinaturas são pagas apenas com cartão: um provider diferente de whop devolve HTTP 400 com o código invalid_provider, e um plan_id desconhecido devolve invalid_plan. Cada período pago substitui os créditos de assinatura restantes pelo valor total do plano; créditos de assinatura não usados não acumulam e os créditos permanentes não são afetados. Assinar o plano que você já tem devolve HTTP 409 com already_subscribed. Mudar para um plano maior o inicia na hora e soma ao novo período os créditos restantes do plano atual; mudar para um menor devolve HTTP 409 com downgrade_requires_cancel. GET /v1/billing/subscription devolve a assinatura ativa em subscription (plan_id, status, current_period_end e cancel_at_period_end) e um pagamento aberto em pending; cada campo é null quando não existe. Só pode haver um pagamento aberto por vez: assinar de novo o mesmo plano devolve o pagamento aberto, escolher outro plano fecha antes o que está aberto, e um pagamento ainda sendo aberto devolve HTTP 409 com checkout_in_progress. POST /v1/billing/subscription/cancel interrompe a renovação no fim do período atual: os créditos de assinatura continuam disponíveis até current_period_end e nada é reembolsado. Devolve a assinatura com cancel_at_period_end em true (chamar de novo devolve o mesmo), HTTP 404 com subscription_not_found quando não há assinatura ativa e HTTP 502 com subscription_cancel_failed quando o cancelamento não pôde ser confirmado; nesse caso, tente de novo. Cada plano em plans também traz um rank: um plano com rank maior é um upgrade em relação a um com rank menor, então leia a direção no rank, não no preço. GET /v1/billing/history lista os pagamentos de assinatura à parte, em subscription_payments (type subscription, payment_id, subscription_id, plan_id, amount_usd, status paid, refunded ou mismatch, period_end e created_at), com paginação própria via subscription_payments_offset e total em subscription_payments_total.

A resposta de GET /v1/generations traz o campo retention_days e cada geração traz expires_at; uma requisição a um arquivo expirado retorna HTTP 410 com o código content_expired. Baixe tudo o que precisar manter por mais tempo. Você também pode excluir uma geração: DELETE /v1/generations/{id} remove o arquivo armazenado na hora e retorna purged_at. Uma geração excluída sai da API: ela não aparece mais em GET /v1/generations, e GET /v1/generations/{id}, o endpoint do arquivo e um segundo DELETE retornam HTTP 404 com o código not_found, como um id que nunca existiu. Os créditos que ela custou não são reembolsados e continuam em GET /v1/billing/history. O registro de uma geração que falhou é excluído após 30 dias; a partir daí GET /v1/generations/{id} e o endpoint do arquivo retornam HTTP 404. Uma geração que ainda está em queued ou processing não pode ser excluída e retorna HTTP 409 com o código generation_in_progress.

Os registros de pagamento são mantidos como comprovantes de cobrança, então uma conta encerrada continua aparecendo no histórico de pagamentos que somos obrigados a manter. O endpoint é autenticado apenas por sessão: ele é chamado na página Conta do Painel, e uma requisição com chave de API é recusada com HTTP 403. Uma conta com um pagamento ainda não liquidado não pode ser encerrada e retorna HTTP 409 com o código pending_payment, porque os créditos desse pagamento ainda podem ser adicionados; o mesmo 409, com merge_in_progress, é retornado enquanto a conta está sendo vinculada a outra. Nos dois casos, aguarde um momento e tente novamente.