Communitygithub.com

Riffkit Skill

Transforme um TikTok vencedor em seu próprio vídeo: mesma fórmula emocional, seu produto, novas imagens. Cole o link (ou faça upload do vídeo), opcionalmente escolha um personagem, produto e idioma, e o backend recria o motivo pelo qual o vídeo prendeu a atenção (gancho, estrutura de ritmo, timing do diálogo) em torno do seu conteúdo. Você faz um riff da fórmula, não do vídeo. Gatilhos: 'riff this video', 'riff this TikTok', 'turn this TikTok into mine', 'remake this viral video with my product', 'recreate this video for my brand'.

O que é Riffkit Skill?

O Riffkit Skill permite que você recrie a fórmula emocional de um vídeo viral de sucesso (como TikTok) para gerar novos vídeos com seu próprio produto, personagem e roteiro. Ele funciona em três modos principais: **adapt** (analisa a estrutura de engajamento do vídeo fonte e a aplica em novas imagens), **swap** (mantém as cenas originais mas substitui o personagem, produto ou cenário) e **creation** (cria vídeos publicitários originais a partir de uma direção criativa escrita). O agente nunca submete tarefas automaticamente: ele elabora um plano (fonte, personagem, produto, ancoragem de conteúdo) e aguarda confirmação explícita do usuário antes de chamar a API. O valor estratégico do agente está em propor a `content_anchor` (direção criativa) — um parâmetro opcional que combina a fórmula da fonte com os pontos fortes do produto. A skill expõe endpoints REST para autenticação, listagem de templates, análise de fontes, geração de vídeos e monitoramento de tarefas, com suporte a múltiplos idiomas e faturamento por créditos.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/riffkit/skills/tree/HEAD/riff-viral-tiktok

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

EndpointPropósito
GET /api/auth/meVerificar estado de autenticação
POST /api/skill/device/authorize · POST /api/skill/device/tokenLogin com um clique (autorização de dispositivo; sem colar token)
POST /api/riffsRiff único (a entrada de geração preferida e quase única)
GET /api/formulasListar templates analisados (uma das fontes)
GET /api/formulas/{id}extraction_summary de um template (o que foi extraído)
POST /api/formulas/analyzeApenas assinantes — analisar uma nova fonte em seu próprio template sem gerar (construir uma biblioteca)
POST /api/formulas/{id}/refresh-analysisReanalisar 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/charactersPersonagens digitais (vinculação opcional) — a criação é limitada, veja "Limites de criação"
GET /api/products · POST /api/products · POST /api/products/{id}/imagesProdutos + imagens de produto (colocação opcional) — a criação é limitada
GET /api/settingsCapacidades 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/languagesCandidatos a idioma do vídeo
GET /api/tasks/batch/{id} · GET /api/tasks/{id}Polling de progresso
GET /api/tasks · GET /api/tasks/statsListar / contar tarefas
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retryCancelar / tentar novamente
GET /api/assetsBuscar vídeos finalizados (vídeo + legenda + hashtags)
POST /api/pipeline/backfill · GET /api/pipeline/backfill/occupiedAdicionar proporções extras a uma renderização já entregue (reformatação) / listar proporções já produzidas
GET /api/usage/creditsSaldo
GET /api/billing/plans · GET /api/billing/subscriptionCatá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_anchor como 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/quote para um riff adapt ou swap (qualquer fonte) e credits_per_ratio de GET /api/pipeline/backfill/occupied para 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 — veja POST /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/quote para um riff adapt ou swap, veja Etapa 3) e pergunte "Enviar?" → na confirmação, chame POST /api/riffs
  • Em HTTP 402, siga "Faturamento e saldo": repasse topup_url literalmente, sem nova tentativa, sem falha silenciosa
  • Chame GET /api/usage/credits apenas 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)

CamadaFunçãoBloqueado porLiberdade
Fórmula + esqueletoGarantia mínima — um mecanismo emocional validado + linguagem de câmeraNa análise do templateNenhuma (mudá-lo anula o valor do riff)
Personagem + produtoConstantes base — o humano digital + fatos do produtoEscolhidos nas configurações (ou padrão)Escolhas diferentes = constantes diferentes, mas constante dentro de uma tarefa
content_anchorDirecionador de teto — qual ângulo de ponto forte, qual superfície preencherAgente + 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 um content_anchor não vazio. Nenhum dos três → 400 cujo detail é uma frase localizada simples (en: "A swap needs at least one change: …"; o corpo não carrega código de erro, então repasse detail em 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 em content_anchor nã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_image em GET /api/characters; busque ${BASE_URL}${reference_image} com o cookie de sessão, como o file_url de 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:

  1. Um template analisado existente (formula_id) — O mais rápido, pois a análise já foi feita. O usuário pode buscá-lo de GET /api/formulas. Opcionalmente, veja seu extraction_summary em GET /api/formulas/{id} antes de prosseguir.
  2. Um link do TikTok (tiktok_url) — O backend baixa, analisa e gera. O URL deve ser de um TikTok.
  3. Um upload de vídeo (video) — O arquivo de vídeo (≤100MB, ≤ limite de render (segundos)). O backend analisa e gera.
  4. Seu próprio vídeo finalizado (source_asset_id) — Apenas para swap, não para adapt. Buscado de GET /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âmetroPadrãoNotas
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)omitidoSem personagem = a própria pessoa da fonte. Se fornecido, o mesmo que adapt.
product_idomitido (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.
visibilityon_cameraSó faz sentido quando um produto está anexado. on_camera: mostrado; off_camera: mencionado, não mostrado; no_product: sem produto.
languageenCandidatos de GET /api/languages (atualmente en / es / pt / id / de / fr / it / ja / zh-CN). Swap ignora: a fonte decide.
content_anchoromitidoDireção criativa opcional. Veja estrutura abaixo.
user_hintomitidoDica 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:

  1. Chame GET /api/riffs/quote com: mode, fonte (um dos formula_id, tiktok_url, video), mais qualquer configuração aplicável (character, product, visibility, language, content_anchor).
  2. 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]".
  3. Pergunte "Enviar?" e aguarde uma resposta afirmativa explícita antes de chamar o endpoint.

Notas especiais:

  • Para tiktok_url ou video, você não pode chamar quote antes de definir user_hint. Mas enquanto você elabora o plano, pode chamar GET /api/riffs/quote com 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/riffs retornar HTTP 402, isso significa que o saldo mudou entre a cotação e o envio. Trate como: relay topup_url diretamente 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

AspectoRiffCriação
Fonte obrigatóriaSim (template / TikTok / upload / asset)Não (escrito do zero)
SaídaVídeo curto de IA (~30-60s) usando uma fórmula testadaVídeo curto de IA original (~30-60s) seguindo uma direção criativa
PreçoDefinido por GET /api/riffs/quote; varia com fonte/configuraçõesSem cotação! Chame POST /api/creation/batch diretamente após confirmação
Confirmação financeiraApresente cotação + "Enviar?"Apenas "Enviar?" sem estimativa

O fluxo de criação:

  1. 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).
  2. (Opcional) Crie um personagem (POST /api/characters com avatar_image) ou um produto (POST /api/products + imagens) para aparecer no vídeo.
  3. Chame POST /api/creation/batch com script (direção criativa), character_ids, product_id, language —— sem cotação.
  4. A resposta retorna batch_id imediatamente. Monitore com GET /api/tasks/batch/{id}.
  5. 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_limits chamando GET /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/characters com name, description, avatar_image (upload de arquivo). O personagem deve ter um avatar carregado (via POST /api/characters/{id}/avatar). O avatar precisa ser aprovado por IA antes de poder ser usado em uma geração. Verifique has_any_active_avatar=true antes de selecionar um personagem para um riff ou criação.
  • Produtos são criados com POST /api/products com name, brand, e opcionalmente description. Para que apareçam no vídeo, faça upload de uma imagem com POST /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 determinado asset_id (o ID de um vídeo finalizado na resposta de ativos). A resposta inclui credits_per_ratio (o custo, em créditos, para cada nova proporção) e a lista de ratios já produzidas.
  • POST /api/pipeline/backfill — envie com asset_id e target_ratios (uma lista de proporções para produzir, ignorando as já existentes). O custo é credits_per_ratio por 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 detail com 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]

Fim do documento

Habilidades Relacionadas