Referência da API da Vellria

Envie sua chave de API como token Bearer no cabeçalho Authorization em todas as requisições. As chaves começam com o prefixo vll_ e são criadas na página Chaves de API.

Authorization: Bearer vll_...

GET/v1/models

Os modelos, tamanhos e resoluções válidos, com os custos em créditos. Consulte este endpoint em vez de fixar no código uma tabela de preços do seu lado. Cada tamanho 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), e cada modelo traz max_prompt_length, o limite de caracteres que esse modelo impõe ao prompt (e a qualquer parâmetro de texto livre que não declare o próprio limite). Cada modelo também traz developer, a empresa que o criou (null para um modelo oferecido com o nome 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: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · 1 crédito para qualquer tamanho
• model: vellria-seedream5-pro · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (padrão: enabled) · 8 créditos para qualquer tamanho
• model: vellria-seedream5-pro-edit · edição de imagem · image_urls: 1–10 URLs https (obrigatório) · size: 1536*1536 | 1776*1328 | 1328*1776 | 2048*1152 | 1152*2048 · reasoning: enabled | disabled (padrão: enabled) · 8 créditos para qualquer tamanho + 1 crédito por imagem de referência após a primeira
• model: vellria-qwen-3-image · size: 1024*1024 | 1536*1024 | 1024*1536 | 2048*1152 | 1152*2048 | 2048*2048 · seed: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · negative_prompt: texto, no máximo 10000 caracteres · 5 créditos para qualquer tamanho
• model: vellria-qwen-3-image-edit · edição de imagem · image_urls: 1–3 URLs https (obrigatório) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · negative_prompt: texto, no máximo 10000 caracteres · 5 créditos para qualquer tamanho + 1 crédito por imagem de referência após a primeira
• model: vellria-qwen-3-pro-image · size: 1024*1024 | 1536*1024 | 1024*1536 · seed: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · negative_prompt: texto, no máximo 10000 caracteres · 7 créditos para qualquer tamanho
• model: vellria-qwen-3-pro-edit · edição de imagem · image_urls: 1–3 URLs https (obrigatório) · size: 1024*1024 | 1280*960 | 960*1280 | 1280*720 | 720*1280 | 1440*1440 · seed: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · negative_prompt: texto, no máximo 10000 caracteres · 7 créditos para qualquer tamanho + 1 crédito por imagem de referência após a primeira
• model: vellria-seedream5-lite · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 créditos para qualquer tamanho
• model: vellria-seedream5-lite-edit · edição de imagem · image_urls: 1–14 URLs https (obrigatório) · size: 3072*3072 | 3456*2592 | 2592*3456 | 3744*2496 | 2496*3744 | 4096*2304 | 2304*4096 | 4704*2016 · 5 créditos para qualquer tamanho
• model: vellria-wan26-image · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1440*1440 | 1920*1080 | 1080*1920 · seed: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · negative_prompt: texto, no máximo 10000 caracteres · 6 créditos para qualquer tamanho
• model: vellria-wan26-image-edit · edição de imagem · image_urls: 1–4 URLs https (obrigatório) · size: 1024*1024 | 1280*720 | 720*1280 | 1280*960 | 960*1280 | 1280*1280 | 1664*936 | 936*1664 · seed: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · negative_prompt: texto, no máximo 10000 caracteres · 6 créditos para qualquer tamanho
• model: vellria-wan27-image-edit · edição de imagem · image_urls: 1–9 URLs https (obrigatório) · size: 2K · seed: inteiro 0–2147483647, aleatório quando omitido e devolvido na resposta · 6 créditos para qualquer tamanho

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

POST/v1/uploads

Você não precisa hospedar as imagens de referência por conta própria: envie o arquivo a este endpoint como corpo bruto, receba de volta uma URL pública e use essa URL em image_urls. O cabeçalho Content-Type é obrigatório e deve corresponder ao corpo; os tipos aceitos são image/jpeg, image/png, image/webp, image/bmp e image/gif, com limite de 20 MB por arquivo. Uma imagem usada como referência deve ser um JPEG, PNG, GIF ou WebP estático de até 20 MB, sem áreas transparentes. Metadados como EXIF são removidos quando o arquivo é armazenado. A URL traz um ID impossível de adivinhar e fica armazenada pelo mesmo prazo 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. Toda imagem de referência enviada a POST /v1/generate/image ou POST /v1/generate/video é verificada automaticamente, uma após a outra, antes de qualquer crédito ser gasto: todas as pessoas mostradas devem ser adultas (imagens sem pessoas são aceitas), uma imagem que mostre uma pessoa real conhecida é recusada, assim como uma imagem com texto que tente influenciar a verificação, como instruções ou afirmações sobre idade. Uma requisição recusada retorna HTTP 400 com o código image_blocked e um reason (minor, public_figure ou image_text), sem dizer a qual imagem ele se refere; uma imagem que não pode ser lida retorna HTTP 400 e image_unreadable, com reason animated, transparent ou too_large quando essa for a causa. Toda referência é primeiro armazenada como arquivo enviado (uma imagem informada por URL externa é copiada, sem os metadados) e tanto a verificação quanto o provedor do modelo buscam essa mesma URL de envio, então o provedor recebe exatamente o arquivo verificado. Se a verificação estiver indisponível, a requisição retorna HTTP 503 e moderation_unavailable e nada é cobrado; portanto, gerações com imagens de referência dependem da disponibilidade da verificação. Gerações sem imagens de referência não passam por essa verificação.

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

GET/v1/generations/{id}

As gerações são executadas de forma assíncrona; o status passa por queued → processing → completed (na fila → processando → concluída). Os créditos são reembolsados automaticamente quando uma geração falha.

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

GET/v1/projects

As pastas agrupam suas gerações e nada mais: não custam créditos e nunca mexem em nenhum arquivo. Crie uma com POST /v1/projects (um nome de 1 a 64 caracteres, no máximo 100 pastas por conta), renomeie com POST /v1/projects/{id} e remova com DELETE /v1/projects/{id}. Excluir uma pasta nunca exclui gerações: as linhas continuam e o project_id delas passa a ser null. Coloque uma geração em uma pasta com POST /v1/generations/{id}/project e tire-a de novo enviando project_id: null ao mesmo endpoint. Para consultá-las, GET /v1/generations?project={id} retorna uma pasta e GET /v1/generations?project=none retorna as gerações que não estão em nenhuma pasta. A lista é paginada com limit (de 1 a 50, 20 por padrão) e offset; cada página traz has_more e total, o número de gerações que correspondem aos mesmos filtros.

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

Os créditos são comprados por uma página de pagamento hospedada. GET /v1/billing/packages retorna uma lista única de pacotes, cada um com id, preço em usd e seus créditos, junto com min_usd e max_usd para um valor livre; obtenha esses valores do endpoint em vez de fixá-los no código. POST /v1/billing/create-checkout recebe um package_id dessa lista ou um price_amount livre em USD entre 20 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 concluir o pagamento na página segura do nosso parceiro de pagamento, onde os métodos disponíveis dependem do país dele. 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.

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

Os arquivos gerados ficam armazenados por 14 dias e depois são excluídos do servidor. O registro continua no seu histórico, mas o arquivo fica inacessível. 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 encerrar o prazo de retenção antes: DELETE /v1/generations/{id} remove o arquivo armazenado na hora e registra purged_at, exatamente como a limpeza programada faria. A linha da geração em si nunca é excluída, então os créditos que ela custou continuam visíveis no seu histórico e não são reembolsados, e o endpoint do arquivo passa a responder com o mesmo HTTP 410 e content_expired. Excluir duas vezes não é um erro e retorna o mesmo resultado; 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.

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

DELETE/v1/account

Encerrar a conta exclui suas gerações e os arquivos armazenados delas, seus arquivos enviados, suas chaves de API e suas mensagens de suporte, e encerra sua sessão. Os créditos que restarem na conta são perdidos e não são reembolsados. 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.

20 imagens e 10 vídeos por minuto. As gerações com imagens de referência também compartilham um limite de 120 tentativas por hora, incluindo as recusadas; acima dele, os endpoints de geração retornam o código reference_rate_limited. Ultrapassar um limite retorna HTTP 429; aguarde o tempo indicado no cabeçalho Retry-After e tente novamente.

Seu prompt não é reescrito nem suavizado a caminho do modelo: quando um modelo oferece a reescrita automática do prompt como configuração, ela é enviada desativada. O que resta é uma verificação automática de alcance restrito e uma lista curta de regras, e é só isso.

• Uma verificação automática confere o texto do prompt antes de qualquer crédito ser cobrado e recusa o que reconhece em uma lista fixa de categorias: conteúdo sexual envolvendo menor de idade, zoofilia, incesto entre parentes de sangue, sexo sem consentimento, violência extrema e gore, conteúdo de câmera escondida ou voyeurismo e pedidos de troca de rosto (face swap) ou deepfake, ou que citem uma pessoa real conhecida; a proibição em si é mais ampla do que o que essa verificação detecta. As imagens de referência são verificadas automaticamente da mesma forma antes de qualquer crédito ser cobrado: uma imagem que mostre alguém que possa ter menos de 21 anos ou uma pessoa real conhecida é recusada, assim como uma imagem com texto que tente influenciar a verificação. Uma pessoa real comum, não famosa, não é identificada por nenhuma das verificações; retratá-la sem consentimento é proibido pelos termos, mas não é detectado automaticamente. Tanto a regra sobre menores de idade quanto a regra sobre sexo sem consentimento são de tolerância zero; pelos termos, uma violação encerra a conta sem aviso prévio.
• O provedor que executa o modelo aplica o próprio filtro de segurança e pode recusar uma requisição depois que ela já começou; a geração passa para failed e os créditos cobrados no início são reembolsados automaticamente.