트렌드

트렌드 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는 8~200자의 Idempotency-Key 헤더를 받습니다. 같은 키로 반복된 요청은 첫 실행의 작업으로 응답합니다. 새로 시작되거나 청구되는 것은 없습니다.

권한

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입니다. MCP › 동영상을 참조하세요. confirm 없이 호출한 run_trend는 견적을 반환하고 아무것도 청구하지 않습니다. 사용자가 가격을 수락한 뒤 confirm: true로 호출하면 실행을 시작하고 작업 ID를 반환합니다.