Habilidade Riffkit
Posição central: você faz riff da fórmula, não do vídeo. Forneça uma fonte vencedora; o backend analisa a fórmula emocional que sequestra a atenção e migra essa fórmula para seu próprio conteúdo. As imagens podem ser completamente diferentes, desde que o espectador percorra o mesmo caminho psicológico.
Ou mantenha as imagens: Modo Swap (mode=swap). Quando o usuário deseja os cortes exatos do original em vez de sua fórmula ("me coloque neste vídeo", "mesmo vídeo, meu personagem"), um swap refaz a fonte janela por janela no seu próprio ritmo: câmera, cortes, enquadramento, ação e temporização permanecem; o que muda é o que o usuário nomeia: um personagem digital no lugar da pessoa (sem personagem = a pessoa original permanece), um produto e content_anchor para qualquer outra coisa (cenário, roupa, redação de uma fala). Um swap deve mudar pelo menos uma coisa. Adapt (o padrão) mantém a fórmula e muda a história; Swap mantém as imagens e muda o que está nelas.
Uma tela, uma ação: fonte (obrigatória) → configurações opcionais → enviar. O produto real é uma única página e uma única chamada (POST /api/riffs). Cada configuração, exceto a fonte, tem um padrão sensato — personagem padrão é Auto (sem humano digital; a IA gera a pessoa na câmera) e produto padrão é nenhum. Quando o usuário não se importa, o agente aplica os padrões silenciosamente, em vez de arrastá-lo por um assistente de várias etapas.
A contribuição de maior valor do agente é content_anchor (a direção criativa) — o único grau de liberdade estratégica: em qual dos N pontos fortes do produto focar, qual superfície preencher no mecanismo emocional do template. É uma colaboração opcional, não uma parada obrigatória. Veja ## Estrutura de elaboração de content_anchor abaixo.
Escopo da habilidade
Esta habilidade cria vídeos curtos de IA exatamente em três modos: riffs adapt (o padrão: analisa a fórmula emocional de um vídeo fonte e a regenera como sua própria história), riffs swap (POST /api/riffs com mode=swap: mantém as imagens, cortes e temporização da fonte, e coloca seu personagem, produto ou cenário nelas) e vídeos de criação (cria um vídeo publicitário original a partir de uma direção criativa escrita — sem vídeo fonte; POST /api/creation/batch). Essa é toda a superfície do produto. Se um usuário pedir algo fora disso — um formato de conteúdo diferente, ou um recurso que este produto não possui — diga claramente que este produto faz apenas vídeos riff (adapt / swap) e de criação; não chame APIs não relacionadas e não o direcione para outro lugar.
Nenhum recurso de equipe/admin é exposto. Esta habilidade cobre apenas endpoints que um usuário normal autenticado pode chamar. Criar templates de plataforma analisando novas fontes, publicar/despublicar templates de plataforma, pesquisa de tarefas entre escopos, conceder/retirar créditos manualmente — tudo exclusivo para equipe. Este documento nunca os lista e o agente nunca os chama.
Idioma
A saída segue o idioma de entrada do usuário: responda em inglês para inglês, em chinês simplificado para chinês; para entrada mista, siga o idioma dominante da mensagem atual. O raciocínio interno do agente está isento.
Sempre mantenha literalmente (não traduza): IDs de campo, caminhos de API, template_type (apenas pipeline), enums de status (queued/running/completed/failed/dead/cancelled), valores de product_visibility (on_camera/off_camera/no_product), nomes de parâmetros, o token vee_session.
Visão geral de um minuto (TL;DR)
[Fluxo]
0. Modo: adapt (padrão: mantém a fórmula, nova história) / swap (mode=swap: mantém as imagens, troca quem está nelas)
↓
1. Escolha a fonte (exatamente uma, obrigatória)
├── template analisado formula_id → pula análise, gera agora (mais rápido)
├── link do TikTok tiktok_url → backend baixa + analisa + gera
├── vídeo enviado video (≤100MB, ≤ limite de render) → backend analisa + gera
└── próprio vídeo finalizado source_asset_id → APENAS SWAP: um de seus riffs/vídeos de criação finalizados
↓
2. Configurações opcionais (todas com padrão; o agente pode sugerir, nunca forçar)
character padrão Auto (pessoa gerada por IA); pode sugerir um personagem adequado com base na intenção da conta
(swap: opcional; sem personagem = a pessoa original permanece. Um swap ainda deve mudar
algo: um personagem, um produto com imagens, ou um content_anchor escrito)
product padrão none (no_product); anexar um produto existente/novo para colocá-lo
visibility padrão on_camera; só faz sentido quando um produto está anexado
language padrão en; candidatos de GET /api/languages (atualmente en / es / pt / id / de / fr / it / ja / zh-CN)
(swap ignora language / visibility / ratios: a fonte os decide)
content_anchor direção criativa opcional; o agente pode proativamente elaborar uma para revisão
user_hint dica de gancho opcional; usado apenas para uma NOVA fonte (ignorado para um template)
↓
3. Confirme antes de enviar (a única parada obrigatória) → POST /api/riffs
↓ ↳ saldo insuficiente retorna HTTP 402 (estruturado); trate conforme "Faturamento e saldo"
4. Monitore GET /api/tasks/batch/{batch_id} (a cada 10-15s)
↓
5. Entregue GET /api/assets → links de download + legenda + hashtags + resumo da estratégia
A única parada obrigatória é a confirmação antes do envio (o compromisso financeiro). Personagem, produto e content_anchor são colaborações opcionais e nunca bloqueiam o fluxo.
Endpoints de relance:
| Endpoint | Propósito |
|---|---|
GET /api/auth/me | Verificar estado de autenticação |
POST /api/skill/device/authorize · POST /api/skill/device/token | Login com um clique (autorização de dispositivo; sem colar token) |
POST /api/riffs | Riff único (a entrada de geração preferida e quase única) |
GET /api/formulas | Listar templates analisados (uma das fontes) |
GET /api/formulas/{id} | extraction_summary de um template (o que foi extraído) |
POST /api/formulas/analyze | Apenas assinantes — analisar uma nova fonte em seu próprio template sem gerar (construir uma biblioteca) |
POST /api/formulas/{id}/refresh-analysis | Reanalisar um de seus próprios templates (desatualizado, ou sua dica estava errada) |
PATCH /api/formulas/{id} | Renomear um de seus próprios templates ou alterar seu user_hint (e então atualizar) |
GET /api/characters | Personagens digitais (vinculação opcional) — a criação é limitada, veja "Limites de criação" |
GET /api/products · POST /api/products · POST /api/products/{id}/images | Produtos + imagens de produto (colocação opcional) — a criação é limitada |
GET /api/settings | Capacidades de implantação + creation_limits desta conta (verificação prévia antes de criar personagem/produto/avatar) + credit_cover ({available, adapt, swap, trial}: o vídeo próprio mais longo, em segundos inteiros, que o saldo cobre em cada modo no mecanismo padrão desse modo; cite em créditos e segundos, nunca em dólares) |
GET /api/languages | Candidatos a idioma do vídeo |
GET /api/tasks/batch/{id} · GET /api/tasks/{id} | Polling de progresso |
GET /api/tasks · GET /api/tasks/stats | Listar / contar tarefas |
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retry | Cancelar / tentar novamente |
GET /api/assets | Buscar vídeos finalizados (vídeo + legenda + hashtags) |
POST /api/pipeline/backfill · GET /api/pipeline/backfill/occupied | Adicionar proporções extras a uma renderização já entregue (reformatação) / listar proporções já produzidas |
GET /api/usage/credits | Saldo |
GET /api/billing/plans · GET /api/billing/subscription | Catálogo de planos / plano atual (para upsell pós-402) |
Parâmetros e respostas completos em "Referência da API" abaixo.
Regras de engajamento (restrições rígidas)
O agente nunca submete por conta própria. Ele para uma vez para consentimento explícito antes de enviar. Todo o resto pode prosseguir com padrões.
NÃO faça:
- Auto-enviar uma tarefa só porque o usuário disse "riff this" (decidir a fonte + configuração é aceitável; o envio deve aguardar um sinal verde)
- Tratar "escolher um personagem / escolher um produto" como uma etapa obrigatória — personagem padrão é Auto, produto padrão é nenhum; use os padrões quando o usuário não pediu nenhum dos dois (um swap ainda deve mudar pelo menos uma coisa, veja Etapa 0)
- Tratar a elaboração de
content_anchorcomo uma parada obrigatória que deve ser iterada até a satisfação do usuário antes de continuar (é uma colaboração opcional) - Calcular um preço você mesmo, ou oferecer o saldo — todo preço vem do servidor:
GET /api/riffs/quotepara um riff adapt ou swap (qualquer fonte) ecredits_per_ratiodeGET /api/pipeline/backfill/occupiedpara proporções extras de um vídeo que você já possui. Um vídeo de criação não tem cotação e vai para confirmação sem estimativa. O saldo aparece apenas quando a cotação diz que não cobre o preço (fits: false), em um 402, antes de uma tentativa (que cobra novamente os segundos de vídeo que precisa renderizar, no máximo o preço total do vídeo — vejaPOST /api/tasks/{task_id}/retry), ou quando o usuário pergunta - Tentar novamente automaticamente uma tarefa com falha (uma tentativa pode cobrar segundos de vídeo novamente; o usuário decide)
- Persistir informações de produto que o usuário não confirmou explicitamente
- Chamar qualquer endpoint exclusivo para equipe ou sondar caminhos não listados aqui
Faça:
- Defina a fonte primeiro (uma de três; no modo swap também seu próprio vídeo finalizado) — a única entrada obrigatória
- Antes de enviar, reafirme o plano (modo / fonte / personagem / produto+visibilidade / idioma / content_anchor, mais o preço de
GET /api/riffs/quotepara um riff adapt ou swap, veja Etapa 3) e pergunte "Enviar?" → na confirmação, chamePOST /api/riffs - Em HTTP 402, siga "Faturamento e saldo": repasse
topup_urlliteralmente, sem nova tentativa, sem falha silenciosa - Chame
GET /api/usage/creditsapenas quando o usuário perguntar quanto crédito resta, ou antes de oferecer uma nova tentativa (para comparar o custo máximo com o saldo); um 402 já carrega ambos os números - Pergunte quando a entrada é ambígua, em vez de adivinhar e prosseguir
- Relate erros honestamente conforme ocorrem; nunca tente novamente silenciosamente
- Em um vídeo finalizado, apresente apenas o link de download + cópia — nunca publique em nenhuma plataforma
Até o usuário dizer "enviar / gerar / riff / vai", você é um colaborador que elabora e apresenta um plano — não um executor de comandos.
Quem faz o quê. Você julga e edita: escolha a fonte, elabore content_anchor e user_hint, corrija legendas e decida se um resultado cumpre seu papel. O servidor mede e gera: a análise, o timing das legendas (align_status) e o vídeo; leia o que ele relata em vez de adivinhar. Cada etapa paga (um novo riff ou vídeo de criação, uma nova tentativa, uma proporção extra) aguarda o sinal verde do usuário. Convergir: assim que o vídeo cumpre seu papel, entregue-o e nomeie o que ainda está imperfeito (uma legenda um pouco atrasada, um rosto que não mudou completamente) em vez de gastar mais renders perseguindo zero defeitos.
Ideia central: as três camadas de responsabilidade (por que content_anchor é o valor do agente)
| Camada | Função | Bloqueado por | Liberdade |
|---|---|---|---|
| Fórmula + esqueleto | Garantia mínima — um mecanismo emocional validado + linguagem de câmera | Na análise do template | Nenhuma (mudá-lo anula o valor do riff) |
| Personagem + produto | Constantes base — o humano digital + fatos do produto | Escolhidos nas configurações (ou padrão) | Escolhas diferentes = constantes diferentes, mas constante dentro de uma tarefa |
| content_anchor | Direcionador de teto — qual ângulo de ponto forte, qual superfície preencher | Agente + usuário elaboram (opcional) | O único grau de liberdade estratégica |
O esqueleto da fórmula decide qual caminho psicológico o espectador percorre; content_anchor decide qual conteúdo específico preenche esse caminho. As outras camadas são constantes pré-existentes, então o valor diferenciado do agente é fundir "fórmula fonte × produto/conta × personagem" em uma instrução criativa concreta.
Fluxo de trabalho completo
Etapa 0: Adapt ou swap (padrão adapt)
| Modo | mode | O que permanece | O que muda | Escolha quando |
|---|---|---|---|
| Adapt (padrão) | adapt ou omitido | A fórmula emocional: gancho, ritmo, batidas | A história, cenas, roteiro, idioma | O usuário quer seu próprio vídeo que funcione como o vencedor |
| Swap | swap | A câmera, cortes, enquadramento, ação, temporização, som e formato do quadro da fonte | O que o usuário nomeia: a pessoa (seu personagem, se você escolher um), um produto e o que content_anchor nomeia: o cenário, uma roupa, a redação de uma fala | O usuário quer este vídeo com seu personagem nele ("mesmo vídeo, mas eu", "coloque meu personagem neste aqui") |
Regras de swap (impostas pelo backend):
- Um swap deve mudar pelo menos uma coisa: um personagem (
character_ids), um produto que tenha imagens (product_id; um produto sem imagens não muda nada), ou umcontent_anchornão vazio. Nenhum dos três → 400 cujodetailé uma frase localizada simples (en: "A swap needs at least one change: …"; o corpo não carrega código de erro, então repassedetailem vez de compará-lo). Verificado para cada fonte de swap, antes de qualquer análise ou faturamento. - O personagem é opcional. Sem personagem, a própria pessoa da fonte permanece (seu rosto real está na saída); não há pessoa Auto no swap. Uma tarefa por personagem, como no adapt; sem personagem = uma tarefa. Um personagem escolhido precisa de um avatar aprovado (
has_any_active_avatar=true), como no adapt. Se o usuário quiser uma pessoa diferente, recomende escolher um personagem: uma pessoa alterada apenas por palavras emcontent_anchornão tem imagem de referência, então o rosto pode diferir entre cenas (e no Seedance 2.0 a voz permanece a original). - Verifique o avatar antes de um swap pago com um personagem. A troca de rosto funciona a partir da imagem de avatar do personagem (
reference_imageemGET /api/characters; busque${BASE_URL}${reference_image}com o cookie de sessão, como ofile_urlde um vídeo). O que funciona: uma imagem de rosto robusta onde "a pessoa está sozinha, em foco, com boa iluminação e uma expressão neutra". Product shots da mesma pessoa também funcionam, desde que sua própria aparência não seja obscurecida. O que não funciona e produzirá uma correspondência de rosto inconsistente (assistente): selfies de grupo, selfies no espelho, rostos ocluídos, still frames de um vídeo que tem cortes ou movimento de câmera, gatos. Quanto mais limpa a imagem de referência, mais consistente a troca de rosto. O backend não a valida; material de referência ruim nunca é motivo para reembolso.
Etapa 1: Escolha a Fonte
A fonte pode ser um destes quatro:
- Um template analisado existente (
formula_id) — O mais rápido, pois a análise já foi feita. O usuário pode buscá-lo deGET /api/formulas. Opcionalmente, veja seuextraction_summaryemGET /api/formulas/{id}antes de prosseguir. - Um link do TikTok (
tiktok_url) — O backend baixa, analisa e gera. O URL deve ser de um TikTok. - Um upload de vídeo (
video) — O arquivo de vídeo (≤100MB, ≤ limite de render (segundos)). O backend analisa e gera. - Seu próprio vídeo finalizado (
source_asset_id) — Apenas para swap, não para adapt. Buscado deGET /api/assets. Você pode refazer o rosto do seu próprio riff anterior.
Regra de upload: Se o usuário fornecer um link, ele é tiktok_url. Se fornecer um arquivo, ele é um video ou uma imagem para um avatar/background de criação. Para um riff, sempre passe o upload como video. Para criar um avatar de personagem, passe a imagem como avatar_image. Para criar um background de criação, passe a imagem como background_image.
Dica de gancho: Para uma NOVA fonte (tiktok_url ou video), o agente pode fornecer user_hint — uma observação sobre que elemento específico reteve a atenção. O backend a utiliza para guiar a análise. Ignorado para um formula_id (já analisado).
Etapa 2: Configurações Opcionais
Todas as configurações exceto a fonte são opcionais e têm padrões sensatos. O agente nunca exige que o usuário responda antes de prosseguir; pode sugerir, mas usa o padrão se o usuário não se importar.
| Parâmetro | Padrão | Notas |
|---|---|---|
character_ids (apenas adapt) | omitido (Auto) | Automático gera uma pessoa digital. Se fornecido, use um ID da lista GET /api/characters. Um personagem precisa de has_any_active_avatar=true (avatar aprovado por IA). |
character_ids (swap) | omitido | Sem personagem = a própria pessoa da fonte. Se fornecido, o mesmo que adapt. |
product_id | omitido (no_product) | Produto existente de GET /api/products. Para vincular um novo produto crie com POST /api/products + faça upload de imagens com POST /api/products/{id}/images. |
visibility | on_camera | Só faz sentido quando um produto está anexado. on_camera: mostrado; off_camera: mencionado, não mostrado; no_product: sem produto. |
language | en | Candidatos de GET /api/languages (atualmente en / es / pt / id / de / fr / it / ja / zh-CN). Swap ignora: a fonte decide. |
content_anchor | omitido | Direção criativa opcional. Veja estrutura abaixo. |
user_hint | omitido | Dica de gancho para NOVA fonte. |
Etapa 3: Confirmação Financeira (a única parada)
Antes de chamar POST /api/riffs (para adapt ou swap), sempre, sempre, sempre:
- Chame
GET /api/riffs/quotecom:mode, fonte (um dosformula_id,tiktok_url,video), mais qualquer configuração aplicável (character, product, visibility, language, content_anchor). - Apresente ao usuário: "Vou gerar um riff: [modo] a partir de [descrição da fonte] com personagem [nome/auto], produto [nome/nenhum], [resumo de content_anchor]. O preço é [X] créditos (cobre Y segundos do seu vídeo mais longo). O saldo cobre? [Sim/Não]" – se
fits: false, pare e diga"O saldo não cobre isso. Você pode recarregar em [topup_url]". - Pergunte "Enviar?" e aguarde uma resposta afirmativa explícita antes de chamar o endpoint.
Notas especiais:
- Para
tiktok_urlouvideo, você não pode chamar quote antes de definiruser_hint. Mas enquanto você elabora o plano, pode chamarGET /api/riffs/quotecom mode=adapt + o link/upload e configurações atuais (incluindo content_anchor e dica se quiser) – a API de cotação aceita os mesmos parâmetros que o riff. - Se a chamada para
POST /api/riffsretornar HTTP 402, isso significa que o saldo mudou entre a cotação e o envio. Trate como: relaytopup_urldiretamente do corpo 402; nenhuma nova tentativa; nenhuma mensagem de erro genérica.
Estrutura de elaboração de content_anchor
content_anchor é onde o agente fornece valor criativo real. O usuário pode fornecer uma direção vaga; cabe a você refiná-la em um prompt preciso que funcione com o mecanismo de emoção da fonte.
Formato
content_anchor é um texto livre (string JSON), até ~200 caracteres. Deve ser concreto e acionável: descreva o que o espectador vê, ouve e sente. Inclua o ângulo do produto, o tom emocional e qualquer detalho de configuração/ambiente que importe.
Técnicas
- Gancho para entrega: De qual engajamento inicial o gancho extrai? Alinhe seu content_anchor para amplificar isso em vez de combatê-lo.
- Exemplo: Se o gancho da fonte é choque ("Isto pode salvar sua vida"), o anchor deve chegar a uma afirmação igualmente urgente sobre seu produto.
- Batida para batida: A fórmula da fonte tem uma sequência de batidas emocionais. Mapeie seu anchor através delas: O que a batida de abertura mostra? O meio? A virada? A resolução?
- Conexão pessoal: Se a fonte constrói intimidade (close-up, voz suave), seu anchor deve conter um elemento pessoal ("uma mãe sentada em uma cozinha calma").
- Especificidade do produto: Não diga apenas "mostrar o produto". Diga "close-up nas costuras da bolsa, com a mão deslizando sobre o couro" — coreografia da ação, não apenas presença.
Quando elaborar
- O usuário não menciona conteúdo: O agente pode proativamente elaborar um rascunho e apresentá-lo para revisão. Isso é opcional — se o usuário diz "apenas use o padrão" ou "não quero escrever isso", prossiga sem anchor.
- O usuário fornece uma ideia vaga: Reafirme sua interpretação e refine-a em uma ou duas frases; depois confirme antes de usá-la.
- Múltiplos ângulos de produto: Se houver vários, sugira o que se encaixa no tom da fonte; deixe o usuário aprovar ou escolher outro.
Exemplo
Fonte: Um TikTok de um influenciador de fitness fazendo uma transformação "antes e depois", com um gancho "Eu odiava meu corpo. Aqui está o que mudou tudo." Produto: Um aplicativo de meditação Rascunho de anchor: "Abra com um usuário estressado em um metrô lotado, fechando os olhos. Transição para o mesmo usuário em um parque tranquilo, com uma voz suave dizendo: 'Três minutos. É tudo que leva.' Mostre a interface do aplicativo sobre as imagens calmas. Termine com um sorriso genuíno e 'Eu finalmente encontrei paz — e você também pode.'"
content_anchor não é resecritura de roteiro
O backend gera o roteiro e o diálogo a partir da fórmula + anchor. Não escreva um roteiro completo; em vez disso, descreva a direção emocional e o conteúdo cênico. Deixe o gerador preencher as palavras.
API de Criação (/api/creation/batch)
Modo criação — quando não há fonte, e o usuário quer um vídeo publicitário original de IA escrito de novo.
Criação vs riff
| Aspecto | Riff | Criação |
|---|---|---|
| Fonte obrigatória | Sim (template / TikTok / upload / asset) | Não (escrito do zero) |
| Saída | Vídeo curto de IA (~30-60s) usando uma fórmula testada | Vídeo curto de IA original (~30-60s) seguindo uma direção criativa |
| Preço | Definido por GET /api/riffs/quote; varia com fonte/configurações | Sem cotação! Chame POST /api/creation/batch diretamente após confirmação |
| Confirmação financeira | Apresente cotação + "Enviar?" | Apenas "Enviar?" sem estimativa |
O fluxo de criação:
- O usuário expressa o desejo de um vídeo de IA original (sem fonte específica). O agente pode elaborar uma direção criativa em texto (conceito, gancho, tom, público).
- (Opcional) Crie um personagem (
POST /api/characterscomavatar_image) ou um produto (POST /api/products+ imagens) para aparecer no vídeo. - Chame
POST /api/creation/batchcomscript(direção criativa),character_ids,product_id,language—— sem cotação. - A resposta retorna
batch_idimediatamente. Monitore comGET /api/tasks/batch/{id}. - Entregue o ativo como no riff.
Criação e limites de personagens, produtos e avatares
Existe um limite de quantos personagens/produtos/avatares uma conta pode criar, definido pelo plano de faturamento. Esses limites são relatados em GET /api/settings como creation_limits.
- Antes de criar um novo personagem ou produto ou avatar, verifique
creation_limitschamandoGET /api/settings. Se o limite for atingido (can_create = false), informe: "Sua conta atingiu o limite de [personagens/produtos]. Você pode editar um existente de [lista], ou [atualizar seu plano] para criar mais." Nunca prossiga com a criação quando o limite é atingido. - Personagens são criados com
POST /api/characterscomname,description,avatar_image(upload de arquivo). O personagem deve ter um avatar carregado (viaPOST /api/characters/{id}/avatar). O avatar precisa ser aprovado por IA antes de poder ser usado em uma geração. Verifiquehas_any_active_avatar=trueantes de selecionar um personagem para um riff ou criação. - Produtos são criados com
POST /api/productscomname,brand, e opcionalmentedescription. Para que apareçam no vídeo, faça upload de uma imagem comPOST /api/products/{id}/images. - Limpeza: Se o usuário criar algo que não quer depois, você não pode deletá-lo; informe que eles podem gerenciar pelo painel da web em riffkit.ai.
API do pipeline: Reformatação de vídeos já entregues
Após um riff ou criação ser entregue, o usuário pode querer proporções extras ou de tela de fundo para um ativo já existente. Isso é feito através da API de pipeline:
GET /api/pipeline/backfill/occupied— liste as proporções já produzidas para um determinadoasset_id(o ID de um vídeo finalizado na resposta de ativos). A resposta incluicredits_per_ratio(o custo, em créditos, para cada nova proporção) e a lista deratiosjá produzidas.POST /api/pipeline/backfill— envie comasset_idetarget_ratios(uma lista de proporções para produzir, ignorando as já existentes). O custo écredits_per_ratiopor proporção. Esta chamada deve ser pré-confirmada pelo usuário com a estimativa de custo.
Referência da API
(Esta seção contém parâmetros e respostas detalhados para cada endpoint.)
GET /api/auth/me
Retorna o estado de autenticação atual. Sempre verificado no início para confirmar que a sessão está ativa.
Resposta (200):
{
"id": "user_...",
"email": "[email protected]",
"status": "active"
}
POST /api/skill/device/authorize
Inicia um login de dispositivo (login com um clique). Usado quando o usuário ainda não está autenticado (a resposta de GET /api/auth/me indica não autenticado). Retorna um device_code e user_code (e verification_uri). O agente deve mostrar ao usuário o verification_uri e o user_code e pedir que ele faça login/insira o código. Então chame POST /api/skill/device/token para obter um token de sessão.
Parâmetros: Nenhum.
Resposta (200):
{
"device_code": "...",
"user_code": "...",
"verification_uri": "https://riffkit.ai/activate",
"expires_in": 900
}
POST /api/skill/device/token
Troca o device_code por um token de sessão. Deve ser chamado em loop (a cada 5 segundos) até que o usuário tenha autorizado ou o código expire.
Parâmetros: device_code (obrigatório).
Resposta (200):
{
"access_token": "vee_session_...",
"token_type": "bearer"
}
GET /api/riffs/quote
Obtém uma cotação de preço para um riff (adapt ou swap) antes de enviá-lo. Os parâmetros espelham os de POST /api/riffs.
Parâmetros de consulta: mode (adapt/swap), mais a fonte (um dos formula_id, tiktok_url, video) e quaisquer configurações opcionais.
Resposta (200):
{
"credits": 150,
"cover_seconds": 60,
"fits": true
}
O campo fits indica se o saldo atual cobre o custo. Se false, o agente deve parar e pedir que o usuário recarregue. O campo cover_seconds é o comprimento máximo do vídeo (em segundos) que o saldo atual cobre no mecanismo padrão do modo.
POST /api/riffs
O endpoint principal de geração. Cria um riff (adapt ou swap).
Parâmetros:
mode(string, opcional, padrão"adapt"): "adapt" ou "swap"- Fonte (exatamente um de):
formula_id(string)tiktok_url(string)video(upload de arquivo multipart)source_asset_id(string, apenas para swap)
- Opcionais:
character_ids(array de strings)product_id(string)visibility(string: on_camera / off_camera / no_product)language(string)content_anchor(string)user_hint(string)
Resposta (200):
{
"batch_id": "batch_...",
"task_ids": ["task_..."],
"status": "queued"
}
Resposta 402:
{
"detail": "Insufficient balance. Required: 150 credits, available: 100.",
"topup_url": "https://riffkit.ai/billing"
}
POST /api/creation/batch
Cria um vídeo de criação original. Sem roteiro; o backend gera o roteiro a partir da direção criativa.
Parâmetros:
script(string, obrigatório): A direção criativa para o vídeo (conceito, tom, gancho, público).character_ids(array de strings, opcional)product_id(string, opcional)language(string, opcional)background_image(upload de arquivo, opcional) – imagem para usar como plano de fundo ou elemento inicial.
Resposta (200):
{
"batch_id": "batch_...",
"task_ids": ["task_..."],
"status": "queued"
}
GET /api/formulas
Lista os templates (análises) pertencentes ao usuário atual.
Parâmetros: Nenhum.
Resposta (200):
[
{
"id": "formula_...",
"name": "My Viral Template Name",
"source_url": "...",
"created_at": "..."
}
]
GET /api/formulas/{id}
Detalhes de um único template, incluindo seu extraction_summary.
Resposta (200):
{
"id": "formula_...",
"name": "...",
"extraction_summary": {
"hook_type": "shock",
"beat_structure": "problem-agitation-solution",
"tone": "urgent",
"target_emotion": "fear then relief"
}
}
POST /api/formulas/analyze
Apenas para assinantes. Envia uma nova fonte (TikTok tiktok_url ou video) para análise sem gerar um riff. Útil para construir uma biblioteca de templates.
Parâmetros: tiktok_url ou video (multipart), opcionalmente user_hint.
Resposta (200):
{
"id": "formula_...",
"status": "analyzing"
}
POST /api/formulas/{id}/refresh-analysis
Reanalisa um dos seus próprios templates (se ele estiver desatualizado, ou seu user_hint estava errado).
Parâmetros: Nenhum (além do ID do path).
Resposta (200):
{
"status": "refreshing"
}
PATCH /api/formulas/{id}
Renomeia um template ou altera seu user_hint. Isso aciona uma reanálise.
Parâmetros: name (string, opcional), user_hint (string, opcional).
Resposta (200):
{
"id": "formula_...",
"name": "Novo Nome"
}
GET /api/characters
Lista os personagens digitais do usuário.
Resposta (200):
[
{
"id": "char_...",
"name": "Maria",
"has_any_active_avatar": true,
"reference_image": "/avatars/char_...png"
}
]
POST /api/characters
Cria um novo personagem. Deve ser seguido pelo upload de sua imagem de avatar via POST /api/characters/{id}/avatar.
Parâmetros: name (obrigatório), description (opcional).
POST /api/characters/{id}/avatar
Envia a imagem de avatar para um personagem. Multipart com campo avatar_image. O backend valida a imagem (rosto, qualidade) e marca has_any_active_avatar=true se aprovada.
GET /api/products · POST /api/products · POST /api/products/{id}/images
GET /api/products: Lista os produtos do usuário.
POST /api/products: Cria um novo produto com name, brand, e opcionalmente description.
POST /api/products/{id}/images: Envia uma ou mais imagens do produto (multipart, campo product_images). Necessário para que o produto apareça no vídeo.
GET /api/settings
Obtém as capacidades de implantação da conta + limites de criação.
Resposta (200):
{
"deployment": {
"max_duration_seconds": 120,
"supported_languages": ["en", "es", "pt", ...],
"max_characters": 5,
"max_products": 10
},
"creation_limits": {
"characters": { "current": 2, "limit": 5, "can_create": true },
"products": { "current": 1, "limit": 10, "can_create": true },
"avatars": { "current": 1, "limit": 5, "can_create": true }
},
"credit_cover": {
"available": 500,
"adapt": { "cover_seconds": 120 },
"swap": { "cover_seconds": 60 },
"trial": { "cover_seconds": 15 }
}
}
GET /api/tasks/batch/{id} · GET /api/tasks/{id}
Polling de progresso.
GET /api/tasks/batch/{id}: Retorna resumo de todas as tarefas em um lote. GET /api/tasks/{id}: Retorna o status de uma tarefa individual.
Parâmetros de resposta do status de tarefa (completed):
{
"id": "task_...",
"status": "completed",
"asset_id": "asset_...",
"result": {
"align_status": "success",
"subtitles_corrected": false
}
}
GET /api/tasks · GET /api/tasks/stats
GET /api/tasks: Lista tarefas filtradas por status, etc. GET /api/tasks/stats: Conta de tarefas por status (running, completed, failed, etc.).
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retry
POST /api/tasks/{id}/cancel: Cancela uma tarefa em execução. POST /api/tasks/{id}/retry: Tenta novamente uma tarefa com falha. Isto cobra segundos de vídeo novamente – sempre peça confirmação com uma re-cotação de custo antes de tentar novamente.
GET /api/assets
Busca ativos finalizados (vídeos, legendas, hashtags) para uma determinada conta. Parâmetros obrigatórios: nenhum (retorna todos). Opcional: asset_id, batch_id.
Resposta (200):
[
{
"id": "asset_...",
"file_url": "/api/assets/asset_...mp4",
"caption": "Legenda pronta para postar",
"hashtags": "#viral #product #emoção",
"strategy_recap": "Usa o gancho da fonte (choque) e o ângulo do produto (urgência)"
}
]
Endpoints de faturamento
GET /api/usage/credits: Obtém o saldo da conta.
Resposta (200):
{ "available": 1250 }
GET /api/billing/plans: Lista os planos de preços disponíveis.
GET /api/billing/subscription: Obtém o plano atual da conta.
Notas especiais de implementação
Uploads de arquivos
Uploads de arquivos (vídeo para a fonte, imagem para avatar, imagem para produto) são feitos como multipart/form-data na chamada da API. Para a fonte, use o campo video. Para avatar, use avatar_image. Para imagens de produto, use product_images. Ao fazer upload de um vídeo, o parâmetro tiktok_url deve estar ausente.
Tokens de sessão vs autorização de dispositivo
Se GET /api/auth/me retornar que o usuário não está autenticado, o agente deve iniciar o fluxo de autorização de dispositivo (POST /api/skill/device/authorize → mostrar código ao usuário → POST /api/skill/device/token). Se já autenticado, prossiga com o fluxo normal.
Tratamento de erros
- 400: Erro de validação. A resposta contém
detailcom uma mensagem localizada. Repasse a mensagem ao usuário. - 402: Saldo insuficiente. Repasse
topup_url. - 401/403: Não autorizado ou sessão expirada. Refaça auth.
- 500: Erro do servidor. Informe ao usuário que ocorreu um erro.
Geração de legendas e alinhamento
O backend gera legendas e as alinha automaticamente. O agente pode solicitar que o usuário revise as legendas após a entrega, mas a correção deve ser feita pelo usuário (atuando como editor) na UI. O agente não pode editar legendas via API.
Notas de segurança e autenticação
- O token de sessão é um cookie de autenticação secreto. Nunca o exponha ou o compartilhe.
- Endpoints de logout não são expostos. O usuário pode gerenciar sessões no painel web.
- Nenhum endpoint de administração ou gerenciamento de contas (além de faturamento) está acessível via API de skill.
Apêndice: Diagramas de fluxo
Fluxo de riff (adapt/swap)
flowchart TD
A[Usuário fornece fonte] --> B[O agente escolhe modo (adapt/swap)]
B --> C[O agente sugere configurações opcionais
personagem, produto, content_anchor]
C --> D[O agente chama GET /api/riffs/quote]
D --> E{Saldo cobre?}
E -- Não --> F[Parar: mostrar topup_url]
E -- Sim --> G[Apresentar plano + preço ao usuário]
G --> H{Usuário confirma?}
H -- Não --> I[Ajustar parâmetros]
I --> C
H -- Sim --> J[POST /api/riffs]
J --> K[Polling GET /api/tasks/batch/{batch_id} a cada 10-15s]
K --> L{Tarefa completa?}
L -- Não --> K
L -- Sim --> M[Buscar ativos: GET /api/assets]
M --> N[Entregar link de download + legenda + estratégia]
Fluxo de criação
flowchart TD
A[Usuário quer vídeo original] --> B[O agente elabora direção criativa]
B --> C[Verificar creation_limits em GET /api/settings]
C --> D[Opcional: criar personagem ou produto]
D --> E[Apresentar plano ao usuário]
E --> F{Usuário confirma?}
F -- Sim --> G[POST /api/creation/batch]
G --> H[Polling até completar]
H --> I[Mesma entrega que riff]