アプリとテンプレート
TypeScript から、公開された Nodaro のアプリを閲覧して実行し、実行履歴を読み取り、ワークフローのテンプレートをプロジェクトに複製し、チュートリアルを一覧表示します。
client.apps は、公開されたアプリ(入力と出力のシンプルなフォームで包んだワークフロー)を閲覧し、実行します。client.templates はテンプレートマーケットプレイスを閲覧し、テンプレートをあなたのプロジェクトの 1 つに複製します。client.tutorials は、チュートリアル動画とチュートリアルワークフローを一覧表示します。概念については、アプリとチュートリアルとテンプレートを参照してください。
メソッド
| メソッド | 内容 |
|---|---|
apps.list(params?) | 公開されたアプリを閲覧します |
apps.get(slug) | アプリを、その入力と出力とともに読み取ります |
apps.run(slug, inputs?, opts?) | アプリを実行します |
apps.listRuns(slug, params?) | アプリの自分の実行を一覧表示します |
apps.getRun(slug, runId) | 1 件の実行を読み取ります |
apps.resume(slug, runId, opts?) | 失敗した実行を、止まった所から再試行します |
apps.deleteRun(slug, runId) | 実行をアーカイブします |
templates.browse(params?) | テンプレートマーケットプレイスを閲覧します |
templates.get(slug) | テンプレートを、そのワークフローとともに読み取ります |
templates.clone(slug, params) | テンプレートをプロジェクトに複製します |
tutorials.list() | チュートリアルをカテゴリー別に一覧表示します |
client.apps
list() と get() は公開されています。run() と実行履歴は、ログイン中の呼び出し元として動作します。
apps.list(params?)
公開されたアプリを、ページ単位で閲覧します。
list(params?: { search?: string; category?: string; limit?: number; cursor?: string }): Promise<{
data: PublishedApp[]
nextCursor?: string | null
}>プロパティ
型
const { data: apps, nextCursor } = await client.apps.list({ search: "headshot", limit: 20 })このメソッドは GET /v1/apps/browse を呼び出します。アプリのページを隠すデプロイメント(nav.hide に apps を指定)では、一覧にアプリが表示されず、{ data: [], nextCursor: null } が返ります。デプロイメントは、公開作品をオフにすることもできます(outputs.allowPublic: false)。その場合、マーケットプレイスには何も表示されず、{ data: [], nextCursor: null } が返ります。また、アプリはその作成者だけのものになります。他人のアプリの get()、run()、resume() は、存在しないアプリと同じく NotFoundError をスローします。そのアプリを自分で実行した過去の記録は、listRuns() と getRun() で引き続き読めます。
PublishedApp は、id、slug、name、description、creatorId、creatorName、thumbnailUrl、category、isFeatured、runCount、estimatedCredits、perMinuteCredits、perItemCredits、createdAt、updatedAt を持ちます。
estimatedCredits は、アプリの 1 回の実行あたりの表示価格です。一部のアプリは、渡された録音の長さで料金が決まります。たとえば、編集プランの処理や、エピソード全体のレンダリングです。その場合は perMinuteCredits が 0 より大きく、料金は estimatedCredits に、録音 1 分ごとの perMinuteCredits を足したものです。ユーザーが入力するリスト入力がアプリにある場合は、perItemCredits が 0 より大きくなります。作成者が保存した項目を超える 1 項目ごとに、その数のクレジットが加算されます。
アプリのユーザーが選べる設定によって料金が上がる場合、表示価格は範囲になります。maxEstimatedCredits は、maxPerMinuteCredits と maxPerItemCredits とともに、作成者が設定した制限の範囲内で、アプリの公開フィールドを通じて 1 回の実行にかかりうる最大の料金です。estimatedCredits とその内訳は保存済みの設定での料金で、「〜から」の価格です。max* フィールドは、値が異なる場合にだけ含まれます。UGC 動画は組み合わせごとに料金が計算し直されるので、アプリのユーザーが選べる台本の長さや言語は、最も高い料金で数えられます。範囲の仕組みができる前に公開されたアプリには、次に公開されるまでこれらのフィールドがありません。
estimatedCreditsIsEstimate: true は、従量課金の LLM 呼び出しの見積もりを含む表示価格を示します。アプリ、テンプレート、チュートリアルに含まれます。LLM の呼び出しには、トークンごとの実際の使用分が請求されるので、料金は ≈N と表示してください。固定料金の場合、このフィールドは含まれません。まだ料金のない LLM のモデルを指定したワークフローの公開は、400 validation_error と reason: "llm_model_unpriced" で拒否されます。まだ料金のないモデルを参照してください。保存済みの設定、またはアプリのユーザーが選べる設定で UGC 動画の料金を計算できなかった公開が、無料として掲載されることはありません。そのような公開は、コードと reason が ugc_listing_unpriced の 503 で拒否され、失敗したものを示す choice(たとえば "a choice its users can make (Hebrew, 60 s)"。アプリのユーザーが選べる設定のうち、ヘブライ語で 60 秒のもの、という意味です)が含まれます。何も書き込まれないので、もう一度公開してください。SDK で読み取ると、その code と status を持つ NodaroError になります。
apps.get(slug)
1 つのアプリを、エンドユーザーが入力するフィールドである inputSchema と、返す内容である outputs とともに読み取ります。
get(slug: string): Promise<{ data: PublishedAppDetail }>プロパティ
型
const { data: app } = await client.apps.get("pro-headshot")
console.log(app.inputSchema, app.outputs) // outputs: [{ nodeId, label, type }]runEstimatedCredits、runPerMinuteCredits、runPerItemCredits は、アプリの実行だけの料金です。表示価格から、別に実行されて課金される最終レンダリングの部分を除いたものです。editPlanPerMinute は、編集プランノードが録音の開始した 1 分ごとに課金される場合は true、15、30、60、90、120、180 分の段階で課金される場合は false です。
apps.run(slug, inputs?, opts?)
アプリを実行し、{ executionId, status, runId? } ですぐに返ります。結果は client.executions.get(executionId) をポーリングして取得します。
run(slug: string, inputs?: Record<string, unknown>, opts?: {
inputOverrides?: Record<string, Record<string, unknown>>
}): Promise<{ executionId: string; status: "pending" | "running"; runId?: string }>プロパティ
型
const { executionId } = await client.apps.run("pro-headshot", { photo: photoUrl })
// Add hidden text before the app's prompt, for this run only
await client.apps.run(
"pro-headshot",
{ photo: photoUrl },
{ inputOverrides: { n1: { promptPrefix: "Studio portrait of" } } },
)動画のリンクを受け取るアプリ(公開された動画 URLノードを持つアプリ)は、入力値としてリンクを渡して実行します。たとえば client.apps.run("clip-pack", { episode: "https://www.youtube.com/watch?v=..." }) です。サーバーは、最初のノードが実行される前に投稿のリンクをダウンロードします。4 分以上の YouTube 動画は、inputOverrides で指定した部分だけがダウンロードされます。それ以外のウェブのリンクは、そのまま使われます。
inputOverrides は高度なオプションです。たとえば、ノードのプロンプトの前後のテキスト(promptPrefix と promptSuffix)を設定できます。Webhook 出力の URL や、公開先のアカウント、スクレイパーの対象など、出力ノードの送信先は設定できません。そのようなオーバーライドは、400 locked_field で拒否されます。
apps.listRuns(slug, params?)
アプリの自分の実行を、ページ単位で一覧表示します。
listRuns(slug: string, params?: { limit?: number; cursor?: string }): Promise<{ data: AppRun[]; nextCursor?: string | null }>プロパティ
型
const { data: runs } = await client.apps.listRuns("pro-headshot", { limit: 10 })
for (const run of runs) console.log(run.status, run.outputs)AppRun は、id、appSlug、executionId、status(pending、running、completed、failed、cancelled のいずれか)、inputs、outputs(それぞれ { nodeId, type, url?, text? })、startedAt、finishedAt を持ちます。
apps.getRun(slug, runId)
アプリの 1 件の実行を読み取ります。
getRun(slug: string, runId: string): Promise<{ data: AppRun }>プロパティ
型
const { data: run } = await client.apps.getRun("pro-headshot", runId)apps.resume(slug, runId, opts?)
失敗した実行を、止まった所から再試行します。アプリのページの再試行ボタンと同じです。実行が完了しなかったステップだけが実行され、それらの分だけが課金されます。完了したステップは、それぞれの結果を引き渡します。失敗した UGC クリップは、仕上がっていないクリップだけをレンダリングします。
resume(slug: string, runId: string, opts: { dryRun: true; version?: number }): Promise<{ data: AppRunResumePlan }>
resume(slug: string, runId: string, opts?: { dryRun?: false; version?: number }): Promise<AppRunResumeResult>プロパティ
型
- 実行自体のバージョンと入力。 再試行では、その実行が実行したアプリのバージョンを、その実行が適用した入力で実行します。独自の入力は受け付けません。
- ドライラン。
dryRun: trueを指定すると、応答はAppRunResumePlanです。runId、continuesExecutionId、appVersion、nodeIds、steps({ nodeId, type, label }、もう一度実行されるステップ)、estimatedCredits、reusedClips、sufficient、availableを含みます。estimatedCreditsにはアプリの作成者の手数料が含まれ、クレジットのない環境ではnullです。sufficientは、残高とアプリ用クレジットで再試行をまかなえるかどうかを示します。appCreditsAllowanceは、アプリ用クレジットが原因で再試行できない場合にだけ含まれます。再試行の前に、このプランを表示してください。 - 開始された再試行。
dryRunなしの場合、応答は{ executionId, runId, status: "pending", nodeIds, deduped? }です。client.executions.get(executionId)でポーリングします。実行のワークフロー実行は再試行のものに移るため、そのあとはgetRunに再試行が表示されます。 - 再試行は一度に 1 回。 その再試行が保留中の間に 2 回目の呼び出しを行うと、その実行を示す
AlreadyRunningErrorがスローされます。まったく同時の 2 回の呼び出しだけが同じ再試行に届き、deduped: trueで応答されます。
拒否は、何かが書き込まれたり課金されたりする前に行われます。code は AppRunResumeRefusalCode のいずれかです。
code | スローされるクラス | 発生する場合 |
|---|---|---|
not_found | NotFoundError | このアプリに、自分のその実行がありません。 |
continuation_not_found | NotFoundError | その実行のワークフロー実行が、自分のものではありません。 |
validation_error | NodaroError(400) | 実行 ID かボディの形式が正しくないか、コンポーネントの実行です。 |
app_run_version_unavailable | NodaroError(409) | 実行が使ったバージョンがなくなりました。実行を最初からやり直してください。 |
app_run_version_changed | AppRunVersionChangedError | アプリのバージョンが、実行が実行したバージョンと異なります。最初からやり直すか、version: err.runVersion を送信してください。 |
continuation_workflow_mismatch / continuation_version_mismatch | NodaroError(400) | 実行のワークフロー実行が、別のワークフロー、または別のバージョンを実行しました。実行を最初からやり直してください。 |
continuation_not_failed | NodaroError(409) | 実行は完了したか、停止されました。最初からやり直してください。 |
already_running | AlreadyRunningError(409、executionId) | 実行がまだ進行中か、その再試行が保留中です。executionId を追ってください。 |
continuation_subset_required | NodaroError(409 または 400) | 再試行するものが残っていない(409)か、アプリがステップを実行しません(400)。 |
locked_field | NodaroError(400) | 実行が適用した入力が、アプリで実行する人が設定できないフィールドを設定しています。 |
preview_review_required | NodaroError(400) | 再試行がプレビューで止まりますが、確認する人がいません。アプリのページから再試行してください。 |
insufficient_app_credits / insufficient_credits | InsufficientCreditsError | アプリ用クレジットまたは残高が、再試行の料金に足りません。どちらなのかは code に示されます。 |
billing_unavailable | NodaroError(503) | ワークスペースの実行で、課金が一時的に利用できません。少し待ってから、もう一度お試しください。 |
別の入力で、またはアプリの現在のバージョンで実行するには、代わりに apps.run で実行を最初からやり直します。その場合、すべてのステップがもう一度実行され、再び課金されます。失敗した実行を再試行するを参照してください。
import { AppRunVersionChangedError } from "@nodaro/sdk/errors"
const { data: plan } = await client.apps.resume("pro-headshot", runId, { dryRun: true })
console.log(`${plan.steps.length} step(s) again, about ${plan.estimatedCredits} credits`)
try {
const { executionId } = await client.apps.resume("pro-headshot", runId)
} catch (err) {
if (err instanceof AppRunVersionChangedError && err.runVersion !== undefined) {
// Continue on the run's own version anyway, or start over with apps.run.
await client.apps.resume("pro-headshot", runId, { version: err.runVersion })
}
}apps.deleteRun(slug, runId)
実行をアーカイブします。実行の復元と完全な削除は、Nodaro アプリでしかできないため、スクリプトがデータを破壊することはありません。
deleteRun(slug: string, runId: string): Promise<{ success: true; archived: true }>プロパティ
型
await client.apps.deleteRun("pro-headshot", runId)client.templates
テンプレートマーケットプレイスは、設計上、公開されています。閲覧したり、ワークフロー全体を含むテンプレートを読み取ったり、無料で自分のプロジェクトに複製したりできます。
templates.browse(params?)
マーケットプレイスを、ページ単位で閲覧します(GET /v1/templates/browse)。ログインは不要です。
browse(params?: BrowseTemplatesParams): Promise<{ data: TemplateBrowseCard[]; nextCursor: string | null }>プロパティ
型
const page = await client.templates.browse({ sort: "popular", search: "trailer" })公開作品を許可していないデプロイメント(outputs.allowPublic: false)では、マーケットプレイスには何も表示されず、{ data: [], nextCursor: null } が返ります。
カードの estimatedCredits は、テンプレートの表示価格です。料金がテンプレートに渡す録音の長さで決まる場合は、estimatedPerMinuteCredits が 0 より大きくなります。その場合の料金は、estimatedCredits に、録音 1 分ごとにそのクレジット数を足したものです。それ以外の場合、estimatedPerMinuteCredits はないか 0 です。テンプレート内の選択によって料金が上がる場合、カードには価格帯の上限である maxEstimatedCredits と maxEstimatedPerMinuteCredits も含まれます。
このルートは、テンプレートページのクレジットが少ない順にあたる sort=cheapest も受け付けます。60 分の録音の料金で、安い順に並べます。料金は estimatedCredits に、estimatedPerMinuteCredits の 60 倍を足したものです。SDK の TemplateSort 型には cheapest が含まれないので、client.request() で送ってください。
templates.get(slug)
1 つの公開テンプレートを、そのワークフローのスナップショット全体(snapshotNodes、snapshotEdges、snapshotSettings)とともに読み取ります(GET /v1/templates/:slug)。
get(slug: string): Promise<Template>プロパティ
型
const template = await client.templates.get("noir-trailer")
console.log(template.snapshotNodes.length)スラッグが不明、非掲載、無効のいずれかの場合、NotFoundError をスローします。公開作品を許可していないデプロイメントでは、マーケットプレイスだけに掲載されている他人のテンプレートでも NotFoundError をスローします。チュートリアルのチャンネルにあるテンプレートは、引き続き応答します。
templates.clone(slug, params)
テンプレートを、新しいワークフローとしてあなたのプロジェクトの 1 つに複製します(POST /v1/templates/:slug/clone)。クレジットはかかりません。
clone(slug: string, params: { projectId: string; name?: string }): Promise<{ workflowId: string; projectId: string }>プロパティ
型
const { workflowId } = await client.templates.clone("noir-trailer", { projectId })
await client.workflows.run(workflowId)公開作品を許可していないデプロイメントでは、他人のマーケットプレイスのテンプレートには 404 not_found が返ります。自分のテンプレートとチュートリアルのテンプレートは、これまでどおり複製できます。
client.tutorials
tutorials.list()
すべてのチュートリアルのカテゴリーを、そのチュートリアル動画とチュートリアルワークフローとともに一覧表示します(GET /v1/tutorials)。公開されていて、読み取り専用です。
list(): Promise<{ categories: TutorialCategory[] }>const { categories } = await client.tutorials.list()
for (const category of categories) {
console.log(category.name, category.videos.length, category.flows.length)
}各カテゴリーは、id、name、slug、sortOrder、videos、flows を持ちます。動画は title、videoUrl、thumbnailUrl を持ちます。フローは、チュートリアルとしてマークされたテンプレートです。title、complexity、estimatedCredits、使用するノードタイプとモデル、そして templates.get() と templates.clone() に渡せる slug を持ちます。
よくある質問
コードから Nodaro のアプリを実行するには、どうすればよいですか?
アプリのスラッグと、アプリの入力フィールドに対応するキーを持つ inputs オブジェクトを指定して、client.apps.run を呼び出します。executionId が返るので、結果は client.executions.get(executionId) をポーリングして取得します。
アプリが必要とする入力は、どうすれば分かりますか?
client.apps.get(slug) を呼び出します。その inputSchema には、エンドユーザーが入力するフィールドが一覧表示され、outputs には、アプリが返す内容が一覧表示されます。
テンプレートを複製すると、クレジットがかかりますか?
かかりません。client.templates.clone は、テンプレートを無料であなたのプロジェクトの 1 つに複製します。料金がかかるのは、新しいワークフローを実行したときだけです。
失敗したアプリの実行を、コードから再試行するには、どうすればよいですか?
client.apps.resume(slug, runId, { dryRun: true }) を呼び出して、ステップと料金を確認してから、dryRun なしでもう一度呼び出します。実行が完了しなかったステップだけが実行され、それらの分だけが課金されます。
inputOverrides で、アプリが結果を送る先を変更できますか?
できません。オーバーライドでは、Webhook 出力の URL や公開先のアカウントなど、送信先を設定できません。実行は 400 locked_field で拒否されます。
関連ページ
アプリ(ミニアプリ)
ワークフローとプロジェクト
ジョブと実行
チュートリアルとテンプレート
最終更新