Trends

A API de Trends executa receitas prontas do Cast Swap. Uma trend é um clipe curto com vagas: as pessoas, os pets, os produtos e o lugar que você pode substituir. Preencha as vagas com as suas próprias imagens e execute a trend para receber o clipe de volta com elas.

As trends fazem parte do Nodaro Cloud. Em uma instalação auto-hospedada, todas as rotas respondem 404. As rotas recebem um bearer token. Veja Autenticação.

Só existem aqui as trends publicadas. Um slug de rascunho, não publicado ou desconhecido é um 404 em todas as rotas.

Endpoints

Os nomes, as descrições, os rótulos das vagas e as dicas vêm no idioma de ?locale= quando ele é um idioma da plataforma. Caso contrário, vêm no idioma do seu perfil e, depois, em inglês.

Uma execução continua legível em GET /v1/trends/runs depois que a trend dela passa para uma nova versão ou deixa de ser publicada.

O que uma trend contém

GET /v1/trends/:slug retorna:

• slots: a key, o label, o kind (person, pet, product ou location), o required, uma hint opcional e os chips padrão de cada vaga.
• examples: o vídeo de resultado de cada exemplo e as imagens que cada vaga usou.
• previewSec: 4 quando a trend oferece uma execução de prévia de 4 segundos, senão null.
• resolutions: as resoluções em que a trend pode ser executada.

Um cartão do catálogo em GET /v1/trends traz o slug, o nome, as tags, needs (quantas vagas de cada tipo), a duração em segundos e isFavorite.

O corpo da execução

POST /v1/trends/:slug/estimate e POST /v1/trends/:slug/runs recebem o mesmo corpo: { slots, example?, details?, preview?, resolution?, draft?, sessionId?, projectId? }.

Os chips são os traços próprios do tipo da vaga. Cada chip é "new", feito a partir das suas imagens, ou "original", mantido como no clipe:

{
  "slots": {
    "dancer": { "images": ["https://example.com/me.jpg"], "outfit": "original" }
  },
  "preview": true,
  "resolution": "480p"
}

A cotação

A estimativa responde expectedCredits, o valor que deve ser cobrado pela execução, e holdCredits, o valor reservado quando a execução começa. breakdown lista as partes da cotação.

Repetições

POST /v1/trends/:slug/runs aceita um cabeçalho Idempotency-Key, de 8 a 200 caracteres. Uma repetição com a mesma chave responde com a tarefa da primeira execução. Nada novo é iniciado nem cobrado.

Permissões

Um app OAuth precisa de:

• jobs:read para ler o catálogo, uma trend e as suas execuções;
• workflows:execute para fazer a cotação ou iniciar uma execução, mais assets:write para passar um sessionId;
• assets:write para os favoritos.

Erros

O corpo de uma recusa é { error: { code, message } }. Os erros de vaga também trazem a chave da vaga como slot. As recusas 400 das rotas de cotação e de execução acontecem antes de qualquer cobrança.

Quando o mecanismo de vídeo recusa uma cotação ou uma execução, as rotas de trends respondem com os próprios códigos e mensagens fixas:

Execuções que não terminaram

Uma execução em GET /v1/trends/runs que não terminou tem error: { code, message }. A mensagem é sempre a mesma frase fixa, então decida pelo código:

Uma execução que não falhou e não foi cancelada tem error: null. Uma execução concluída traz videoUrl, posterUrl e creditsCharged. Cada vaga da execução informa se as imagens dela vieram do exemplo (fromExample).

Pelo SDK

client.trends encapsula as rotas. Ele também pode ser importado como @nodaro/sdk/trends.

list(params?: ListTrendsParams): Promise<TrendPage<TrendCard>>
get(slug: string, params?: { locale?: string }): Promise<TrendDetail>
estimate(slug: string, request: TrendRunRequest): Promise<TrendEstimate>
run(slug: string, request: TrendRunRequest, options?: { idempotencyKey?: string }): Promise<{ jobId: string }>
runs(params?: ListTrendRunsParams): Promise<TrendPage<TrendRun>>
favorite(slug: string): Promise<void>
unfavorite(slug: string): Promise<void>

list() e runs() resolvem com a página como ela chega, { data, next }. Passe next de volta como cursor; ele é null na última página. get(), estimate() e run() resolvem com o payload, sem o envelope { data }. "runs" nunca é um slug: os métodos que recebem um slug lançam um TypeError para ele antes de qualquer requisição.

import type { TrendRunRequest } from "@nodaro/sdk"

const { data: cards } = await client.trends.list({ q: "dance" })
const trend = await client.trends.get(cards[0].slug)

const request: TrendRunRequest = {
  // Every required slot needs 1–3 pictures; optional slots left out take the example's.
  slots: Object.fromEntries(
    trend.slots.filter((s) => s.required).map((s) => [s.key, { images: [myPhotoUrl] }]),
  ),
}
const quote = await client.trends.estimate(trend.slug, request)
console.log(`about ${quote.expectedCredits} credits, ${quote.holdCredits} held while it runs`)

const { jobId } = await client.trends.run(trend.slug, request, { idempotencyKey: crypto.randomUUID() })
const job = await client.jobs.get(jobId)

Pela CLI

nodaro trends list --search dance
nodaro trends get <slug>
nodaro trends estimate <slug> --slot dancer=https://example.com/me.jpg --choice dancer.outfit=original
nodaro trends run <slug> --slot dancer=https://example.com/me.jpg --idempotency-key <key>
nodaro trends runs --trend <slug>
nodaro trends favorite <slug>

--slot se repete, com 1 a 3 imagens por vaga. trends run gasta créditos, então execute trends estimate antes. Veja Comandos.

Pelo MCP

Quatro ferramentas MCP cobrem as trends: list_trends, get_trend, estimate_trend e run_trend. Veja MCP › Vídeo. run_trend sem confirm retorna a cotação e não cobra nada. Com confirm: true, depois que o usuário aceita o preço, ela inicia a execução e retorna um ID de tarefa.