Trends

Trends API は、既製の Cast Swap のレシピを実行します。トレンドは、スロットを持つ短いクリップです。スロットは、置き換えられる人物、ペット、商品、場所です。スロットを自分の写真で埋めてトレンドを実行すると、それらが入ったクリップが返されます。

トレンドは Nodaro Cloud の機能です。セルフホスティング環境では、どのルートも 404 を返します。これらのルートは Bearer トークンを受け取ります。認証を参照してください。

ここにあるのは、公開済みのトレンドだけです。ドラフト、非公開、または不明なスラッグは、どのルートでも 404 になります。

エンドポイント

名前、説明、スロットのラベル、ヒントは、?locale= がプラットフォームの言語の場合はその言語で返されます。それ以外の場合は、プロフィールの言語、次に英語で返されます。

トレンドが新しいバージョンに移ったり、非公開になったりした後も、実行は GET /v1/trends/runs で読み取れます。

トレンドの内容

GET /v1/trends/:slug は次のものを返します。

• slots：各スロットの key、label、kind（person、pet、product、location のいずれか）、required、任意の hint、デフォルトのチップです。
• examples：各例の結果の動画と、各スロットで使われた写真です。
• previewSec：トレンドが 4 秒のプレビュー実行に対応している場合は 4、それ以外は null です。
• resolutions：トレンドを実行できる解像度です。

GET /v1/trends のカタログのカードには、スラッグ、名前、タグ、needs（種類ごとのスロットの数）、秒単位の長さ、isFavorite が含まれます。

実行のボディ

POST /v1/trends/:slug/estimate と POST /v1/trends/:slug/runs は、同じボディを受け取ります：{ slots, example?, details?, preview?, resolution?, draft?, sessionId?, projectId? }。

チップは、スロットの種類ごとの特徴です。各チップは、自分の写真から作る "new" か、クリップのまま残す "original" です。

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

見積もり

見積もりは、実行に課金される見込みの expectedCredits と、実行の開始時に確保される holdCredits を返します。breakdown には、見積もりの内訳が示されます。

繰り返し

POST /v1/trends/:slug/runs は、Idempotency-Key ヘッダー（8〜200 文字）を受け取ります。同じキーでの繰り返しには、最初の実行のジョブが返されます。新しく開始や課金されるものはありません。

権限

OAuth アプリには、次のものが必要です。

• カタログ、トレンド、自分の実行を読み取るには jobs:read。
• 実行の見積もりや開始には workflows:execute。sessionId を渡すには、さらに assets:write。
• お気に入りには assets:write。

エラー

拒否のボディは { error: { code, message } } です。スロットのエラーには、スロットのキーも slot として含まれます。見積もりと実行のルートの 400 の拒否は、何かが課金される前に行われます。

動画エンジンが見積もりや実行を拒否した場合、トレンドのルートは独自のコードと固定のメッセージを返します。

完了しなかった実行

GET /v1/trends/runs の実行のうち、完了しなかったものには error: { code, message } が含まれます。メッセージは常に同じ固定の文なので、コードで処理を分岐してください。

失敗もキャンセルもされなかった実行は error: null です。完了した実行には、videoUrl、posterUrl、creditsCharged が含まれます。実行の各スロットには、その写真が例から取られたかどうか（fromExample）が示されます。

SDK から

client.trends はこれらのルートをラップします。@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() と runs() は、届いたままのページ { data, next } に解決されます。next を cursor として渡し直してください。最後のページでは null です。get()、estimate()、run() は、{ data } のエンベロープを除いたペイロードに解決されます。"runs" がスラッグになることはありません。スラッグを受け取るメソッドは、それに対してリクエストの前に TypeError をスローします。

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)

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 は繰り返して指定し、スロットごとに 1〜3 枚の写真を渡します。trends run はクレジットを使うので、先に trends estimate を実行してください。CLI コマンドを参照してください。

MCP から

トレンドを扱う MCP ツールは、list_trends、get_trend、estimate_trend、run_trend の 4 つです。MCP › 動画を参照してください。confirm を指定しない run_trend は、見積もりを返し、何も課金しません。ユーザーが料金を承認した後に confirm: true で呼び出すと、実行を開始してジョブ ID を返します。