Docs

Início rápido

Uma chave, um formato de requisição, todos os modelos de imagem e vídeo. Envie um job, consulte-o, obtenha o arquivo.

Ao vivoTodos os modelos da página de modelos rodam neste endpoint. Imagens e vídeo, um só formato de requisição; as opções e os preços de cada modelo estão em /data/models.json.

NovoModelos de linguagem também. GPT, Claude, Gemini, Grok, DeepSeek, Qwen e mais no POST /v1/chat/completions compatível com a OpenAI, cobrados por token do mesmo crédito: veja chat completions.

URL base	`https://api.revana.si/v1`
Autenticação	`Authorization: Bearer <key>`
Enviar	`POST /v1/generations`
Consultar	`GET /v1/generations/{id}`
Modelos	`GET /v1/models` (sem chave): todos os modelos com que você pode gerar agora
Saldo	`GET /v1/balance`: quanto a conta da sua chave pode gastar
Upload	`POST /v1/uploads`: um link para um arquivo de referência no seu computador
Formato	JSON na entrada, JSON na saída. Preços em USD; 100 créditos = $1.
Legível por máquina	`/openapi.json` · `/llms.txt`

Autenticação

Crie uma chave na sua conta e envie-a como bearer token em todas as requisições. Mantenha-a no seu servidor; nunca a inclua em um navegador ou app mobile.

Enviar uma geração

POSThttps://api.revana.si/v1/generations

Envie o id do modelo e seu input. A resposta volta imediatamente com um id de geração e o status queued; o trabalho acontece em segundo plano.

Campo	Tipo	Descrição
`model`	string, obrigatório	Um id de modelo da página de modelos, ex.: `seedance-2.5`.
`input`	object, obrigatório	O prompt e as configurações; veja os campos de entrada. Campos desconhecidos são recusados.
`max_cost_usd`	number, opcional	O máximo que você pagará por esta geração, até `100` (o padrão). Rotas com preço acima dele são ignoradas; se nenhuma sobrar, a requisição responde `422 max_cost_exceeded`.
`max_wait_s`	integer, opcional	Rotas com expectativa de levar mais do que esse número de segundos são ignoradas. Depois que ele passa, nenhuma nova rota é tentada, mas uma que já esteja rodando pode terminar (até 40 minutos) e é cobrada se entregar.
`Idempotency-Key`	header, opcional	Até 200 caracteres. Envie a mesma chave e o mesmo corpo de novo (após um timeout ou um `503`) e você recebe a mesma geração de volta, não uma segunda. A mesma chave com um corpo diferente é `409 idempotency_conflict`.

Obter o resultado

GEThttps://api.revana.si/v1/generations/{id}

Prefere um endpoint por modelo e webhooks de conclusão? Veja a API de fila compatível com a fal para IDs de requisição, URLs de status/resultado, aliases da fal suportados e limites de migração.

Consulte a cada poucos segundos até status ser succeeded ou failed, depois baixe os arquivos em output.urls com a sua chave: GET /v1/generations/{id}/content para o primeiro, e /content/2, /content/3… quando um modelo de imagem retorna vários. Imagens costumam levar segundos; vídeo leva de menos de um minuto a vários minutos, dependendo do modelo e da duração.

Uma geração concluída:

Campos de entrada

Os mesmos nomes são usados em todos os modelos. Quais campos e valores cada modelo aceita, e seus padrões, estão listados por modelo em /data/models.json (options, tasks). Se um modelo não suporta um campo ou valor, a requisição é rejeitada com 422 invalid_input antes de qualquer cobrança.

Campo	Tipo	Usado para
`prompt`	string	O que gerar. Obrigatório para texto para imagem e texto para vídeo.
`image_url`	string (URL)	Quadro inicial para imagem para vídeo, ou a imagem a editar para imagem para imagem.
`end_image_url`	string (URL)	Último quadro, para modelos com primeiro + último quadro.
`image_urls`	string[]	Imagens de referência, até o limite do modelo.
`resolution`	string	`720p`, `1080p`, `2K`... uma das resoluções do modelo.
`duration`	number	Duração do vídeo em segundos, uma das durações do modelo.
`aspect_ratio`	string	`16:9`, `9:16`, `1:1`...
`audio`	boolean	Gera som junto com o vídeo, onde o modelo suportar. Pode mudar o preço.
`negative_prompt`	string	O que evitar, nos modelos que aceitam isso.
`video_url`	string (URL)	Um clipe a transformar, estender ou ampliar. Sua duração é medida e, nos modelos cobrados por segundo, cobrada.
`audio_url`	string (URL)	A voz ou o som a que um modelo de avatar falante ou de lip-sync se anima.
`quality`	string	Um nível de qualidade nos modelos com preço por nível (ex.: `low`, `medium`, `high`).
`seed`	integer	Uma seed, nos modelos que aceitam uma.

O Seedance 2.5 usa por padrão 720p, 5 segundos (4–30), 16:9 e sem som, e também aceita:

Campo	Tipo	Usado para
`video_url`	string (URL)	Um clipe de 4–30 s a editar. O resultado mantém a duração, então omita `duration`.
`video_urls`	string[]	Clipes de referência, até 10 e 30 segundos no total. Seus segundos são cobrados pela tarifa de entrada de vídeo.
`audio_urls`	string[]	Som de referência, até 10 e 30 segundos no total.

image_url é um primeiro quadro exato, então não pode ser combinado com mídia de referência; use image_urls para uma referência visual mais livre. end_image_url precisa de image_url. A mídia deve ser URLs https públicas que possam ser baixadas diretamente.

Nemesis

nemesis refaz um clipe com as suas próprias pessoas, produtos e lugares: o movimento, o tempo e a câmera do clipe, interpretados por até 8 imagens de referência. O resultado mantém a duração e o formato do clipe. É cobrado pela tarifa de uma edição do Seedance 2.5 mais $0.02 por segundo ($0.08, $0.17 e $0.36 em 480p, 720p e 1080p), por segundo do clipe de entrada mais o vídeo de saída.

Segue a receita do Scenario ALTER: o seu próprio clipe é editado, sem som, com um quadro dele redesenhado com a mudança já feita como primeira referência, e o som original do clipe é recolocado depois. Com mais de uma pessoa, as imagens são associadas da esquerda para a direita conforme as pessoas aparecem no primeiro quadro.

Campo	Tipo	Usado para
`video_url`	string (URL), obrigatório	O clipe de 4–30 s a refazer.
`image_urls`	string[], obrigatório	1–8 imagens de referência.
`roles`	string[]	Um por imagem: `person` (padrão), `product`, `location` ou `look`.
`target_frame`	boolean	Antes do render, o primeiro quadro do clipe é redesenhado com a mudança já feita, na mesma pose, tamanho e luz, e enviado como primeira referência, para que cabelo, rosto e roupas fiquem fiéis às suas imagens. Ligado por padrão para `nemesis`, desligado para `nemesis-lite`. Grátis.
`guide`	string	`nemesis-lite` somente (`nemesis` sempre edita o próprio clipe). `clip` (padrão com um quadro-alvo): segue a imagem do próprio clipe. `people` (padrão sem um): as pessoas são substituídas e o fundo é mantido. `scene`: tudo o que se vê vem das referências e do prompt.
`sound`	string	`original` (padrão ligado em `nemesis`): o som original do clipe é recolocado. `none` (padrão ligado em `nemesis-lite`): sem som.
`face_mesh`	boolean	`nemesis-lite` somente. Rastreia todos os rostos do clipe para que o novo rosto mantenha suas expressões, olhos e lábios. Ligado por padrão com `guide: "people"`, desligado para `scene` e `clip`. Envie `false` para deixá-lo desligado. Nunca é exibido no resultado.
`resolution`	string	`480p`, `720p` (padrão) ou `1080p`.
`prompt`	string	Direção opcional, até 5000 caracteres.

Em nemesis-lite, um clipe sem ninguém, enviado com guide: "people", é recusado com invalid_input e não é cobrado; envie-o com scene ou clip.

Quanto tempo leva. Primeiro o clipe é preparado: em nemesis o quadro-alvo é desenhado, cerca de 15–40 segundos; em nemesis-lite a voz é separada e cada quadro vira o guia de profundidade, cerca de 25 segundos para um clipe de 8 segundos e um minuto e meio para um de 30 segundos. Depois o vídeo é renderizado, que é a maior parte da espera: um clipe de 8 segundos em 480p leva cerca de 4–7 minutos. Consulte a geração até ela terminar.

Nemesis Lite

nemesis-lite aceita a mesma entrada que nemesis e renderiza no Wan 3.0: mais barato, um pouco menos fiel em rostos e detalhes finos. O clipe tem 2–15 s. É cobrado pela tarifa do Wan 3.0 mais $0.02 por segundo ($0.07, $0.11 e $0.19 em 480p, 720p e 1080p), por segundo do clipe de entrada mais o vídeo de saída.

Objeto de geração

Campo	Tipo	Descrição
`id`	string	Id da geração (`gen_…`), usado para consultar.
`object`	string	Sempre `generation`.
`model`	string	O modelo que você pediu.
`status`	string	Veja os status.
`message`	string	Somente enquanto um resultado está sendo confirmado com um provedor: o que está acontecendo.
`quoted_usd`	number	O preço na rota mais barata, que é a tentada primeiro. Se ela não conseguir e uma rota de reserva mais cara conseguir, a cobrança é o preço dessa rota, até `reserved_usd`.
`reserved_usd`	number	O que é reservado do seu saldo: o máximo que esta geração pode custar, se uma rota de reserva mais cara a fizer depois de outras rotas terem sido tentadas. A diferença é liberada quando ela é liquidada. Para nunca pagar mais do que `quoted_usd`, defina `max_cost_usd` com esse valor: as reservas mais caras são então ignoradas.
`output`	object \| null	Quando succeeded: `urls`, os arquivos de resultado (um modelo de imagem pode retornar vários), com `width` e `height`; o vídeo também tem `duration_s` e `has_audio`. Baixe-os logo; os arquivos expiram.
`cost_usd`	number \| null	O que foi cobrado. Definido quando a geração tem sucesso; `0` quando falha.
`attempts`	number	Rotas tentadas, incluindo fallbacks. Apenas a bem-sucedida é cobrada.
`error`	object \| null	Quando failed: `code`, `message` e `retryable`; uma recusa de conteúdo também tem `reason`. Veja por que uma geração falhou.
`created_at`, `completed_at`	string	Timestamps ISO 8601.

Status

Status	Significado
`queued`	Aceita, aguardando uma rota.
`running`	Gerando. Se uma rota falha, o job permanece `running` enquanto passa para a próxima, e enquanto um resultado está sendo confirmado (veja `message`).
`succeeded`	Concluída. `output.urls` contém os arquivos e `cost_usd` o que você pagou.
`failed`	Todas as rotas falharam ou a entrada foi recusada. Nada é cobrado.

Cobrança

Você paga com créditos pré-pagos, 100 por dólar, comprados em pacotes de $10 a $5,000. Todo preço é um número inteiro de créditos.
Quando você envia, reserved_usd é reservado do seu saldo. Se a geração falhar, tudo é liberado.
Você só é cobrado quando a geração tem sucesso, pelo preço cotado para a rota que a fez. Normalmente é a primeira rota, a quoted_usd. Quando uma reserva precisa fazê-la, pode custar mais: o preço dessa rota ou, se uma rota tentada antes dela foi cobrada pelo seu fornecedor, o que essas tentativas custaram mais 10%, o que for maior. Nunca acima de reserved_usd.
Não há cota mensal nem limite por minuto: o seu saldo e max_cost_usd são o limite.
O preço de cada modelo está na página dele e na tabela de preços.

Saldo

GEThttps://api.revana.si/v1/balance

A conta à qual a sua chave pertence. Confira-a antes de um lote grande; não custa nada e não conta para os limites de geração.

Campo	Significado
`available_usd`	O que uma nova geração pode reservar. Um envio cujo `reserved_usd` seja maior recebe `402 insufficient_credits`.
`held_usd`	Reservado por gerações ainda em execução. O que elas não usarem volta quando forem liquidadas.
`balance_usd`	Disponível mais reservado.
`spent_usd`	Cobrado por gerações concluídas, em todo o período.
`*_credits`	Os mesmos valores em créditos (100 por dólar), arredondados para que o disponível nunca apareça maior do que é.

Fazer upload de um arquivo de referência

POSThttps://api.revana.si/v1/uploads

As referências são passadas como links https:// públicos. Para um arquivo na sua própria máquina, peça um link de upload, envie os bytes para lá e use o link que receber de volta. É grátis.

Campo	Significado
`upload_url`	Envie o arquivo para cá com `PUT` em até uma hora, com exatamente os headers em `upload_headers` (tipo e tamanho dele). Qualquer outra coisa é recusada.
`url`	O link do arquivo em `api.revana.si`, válido até `expires_at` (14 dias). Não precisa de chave e redireciona para o arquivo, então qualquer coisa que consiga buscar um link pode lê-lo. Use-o como referência em `POST /v1/generations`. O arquivo é apagado logo depois.
`id`	`upl_…`

Imagens (image/*) até 30 MB, clipes (video/*) até 50 MB, som (audio/*) até 15 MB. Um arquivo maior ou de outro tipo recebe 413 too_large ou 400 invalid_request.

Por que uma geração falhou

Uma geração failed tem error.code, uma message escrita para mostrar a quem a pediu, e retryable: true quando enviar a mesma requisição de novo mais tarde pode funcionar, false quando a própria requisição precisa mudar. Uma geração que falha nunca é cobrada.

Código	Pode tentar de novo	Quando
`content_policy`	no	O modelo recusou o prompt ou a mídia, ou reteve o que criou. `reason` diz qual regra: `sexual` (conteúdo NSFW ou adulto), `minors` (crianças ou adolescentes), `copyright` (material protegido por direitos autorais ou de terceiros, marcas, personagens), `real_person` (a imagem de uma pessoa real ou famosa), ou `other` quando o modelo não dá motivo.
`invalid_input`	no	Uma referência não pôde ser lida, um prompt cita `@Image2` quando uma só imagem foi enviada, ou um valor que o modelo rejeita. A mensagem diz qual.
`model_declined`	no	O modelo respondeu com palavras em vez de criar a imagem ou o vídeo, geralmente porque o prompt pede algo de que ele precisa e que não foi enviado. Faça o prompt descrever o próprio resultado.
`reference_changed`	no	Um arquivo de referência mudou depois de ser verificado. Envie-o de novo.
`max_cost_exceeded`	no	A única rota que poderia rodar custa mais do que `max_cost_usd`.
`model_busy`	yes	Todas as rotas do modelo estavam no limite de capacidade. Tente de novo em um minuto.
`model_unavailable`	yes	Nenhuma rota do modelo pôde aceitar o job agora.
`timeout`	yes	Nenhuma rota retornou um resultado a tempo, ou `max_wait_s` passou.
`all_routes_failed`	yes	Todas as rotas falharam por motivos do lado delas.

Erros

Os erros usam códigos de status HTTP e um corpo JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	Código	Quando
400	`invalid_request`	O corpo não é JSON, não tem `model` ou `input`, ou tem um campo que a API não conhece.
401	`unauthorized`	Chave de API ausente ou inválida.
402	`insufficient_credits`	O seu saldo disponível não cobre `reserved_usd`. Recarregue e tente de novo.
403	`account_disabled`	A conta está pausada. Entre em contato com o suporte.
403	`generation_not_enabled`	Sua chave pode ler preços, mas ainda não pode gerar.
404	`not_found`	Nenhuma geração com este id na sua conta.
409	`idempotency_conflict`	Este `Idempotency-Key` já foi usado com um corpo diferente.
409	`not_ready`	O arquivo foi pedido antes de a geração ter sucesso.
413	`body_too_large`	O corpo tem mais de 1 MB. Envie a mídia como URLs.
422	`invalid_input`	Um campo, valor ou combinação que o modelo não suporta, ou mídia que não pode ser lida. Nada é cobrado.
422	`max_cost_exceeded`	Todas as rotas custam mais do que `max_cost_usd`.
422	`model_not_available`	Nenhum modelo com este id na API. Os ids estão na página de modelos.
429	`rate_limited`	Requisições demais no mesmo segundo de uma conta (uma proteção contra loops descontrolados, não uma cota). Aguarde os `Retry-After` segundos.
429	`concurrency_limit`	A conta já tem o máximo de gerações em andamento. Tente de novo quando uma terminar.
503	`busy`	Um momento de carga. Tente de novo após `Retry-After` com o mesmo `Idempotency-Key`.
503	`model_unavailable`	Nenhuma rota deste modelo está no ar agora. Tente de novo em breve.
500	`server_error`	Algo quebrou do nosso lado. É seguro tentar de novo com o mesmo `Idempotency-Key`.

Lista de modelos

Todos os modelos, suas opções e preços são publicados como JSON em /data/models.json, o mesmo arquivo a partir do qual este site é gerado.