タスクプラグイン API v1 リファレンス

マニフェスト：meta

baseUrlには資格情報、クエリ文字列、フラグメントを含めることはできません。ASCIIホスト名を使用する必要があります。自己ホスト型HTTPまたはプライベートアドレスも許可されます。allowedHostsは host / host:port を使用し、プロトコルやパスは含みません。ポートもマッチングに参加します。デフォルトアドレスは、アクセスを許可するホストの集合を暗黙的に拡大することはありません。

ローカライズされたテキスト

LocalizedTextは文字列または en を含む言語マッピングを使用できます。文字列は英語マッピングに正規化されます。マッチング順序は、現在の言語、主要言語、英語です。

description: {
  en: "Video generation through the vendor API",
  zh: "通过厂商接口生成视频",
  "zh-TW": "透過廠商介面產生影片",
}

プラグインデータ内のテキストは、管理フロントエンドの翻訳キーとして使用すべきではありません。モデル名、フィールドキー、および列挙型の生の値は安定している必要があります。

ライフサイクル フック

すべてのプラグインは、バッチプラグインを含め、meta、buildSubmitRequest、parseSubmitResponse、および parseTaskResult をエクスポートする必要があります。

標準ステータスには、NOT_START、SUBMITTED、QUEUED、IN_PROGRESS、SUCCESS、FAILURE、UNKNOWN が含まれます。不明なステータスは UNKNOWN を返します。不明な結果をデフォルトで処理中と見なすことはできません。

アップストリーム応答のHTTPステータスもホストの判定に関与します。404/410は失敗と返金につながり、401/403、429、5xx、および転送エラーはポーリング失敗として累積されます。TASK_POLL_MAX_FAILURES（デフォルト20）に達すると失敗クリーンアップに入り、タスクタイムアウトメカニズムは依然として外側の期限条件です。

リクエストとクエリコンテキスト

DriverContextは、正規化された requestBody、リクエストヘッダー、アクション、model / upstreamModel、チャネル baseUrl、認証情報、ファイル参照、公開タスクID、およびオプションの originTasks を提供します。

TaskQueryContextは、保存されたタスクから再構築されます。

クエリ側には requestBody がありません。保存されるフィールド名は data であり、raw エイリアスは存在しません。解析フックが state を省略した場合、元の状態が保持されます。明示的に返された場合にのみ更新されます。リクエストとステータス入力は読み取り専用と見なすべきであり、モジュールグローバル変数にタスクデータを保存することに依存すべきではありません。

HTTP記述子とファイル

構築フックは { url, method?, headers?, body?, ... } を返し、ホストによって検証および送信されます。JSONはデフォルトのボディタイプですが、bodyType: "multipart" と parts を使用してマルチパートを構築することもできます。

インバウンドボディはホストによって以下の結合型に統一的に解析されます。

{
  kind: ('json', value);
}
{
  kind: ('form', fields);
}
{
  kind: ('multipart', fields, files);
}
{
  kind: 'none';
}

ファイルは { ref, field, filename, mimeType, size } としてのみJavaScriptに参照として渡され、プラグインはファイルのバイトを直接読み取ることはできません。マルチパートのアウトバウンドでは parts[].fileRef を使用します。JSONのアウトバウンドではプレースホルダーを埋め込むことができ、ホストによってエンコードされたコンテンツに置き換えられます。

{ __fileRef: "request_file:input_reference", encoding: "base64" }
{ __fileRef: "request_file:input_reference", encoding: "dataUrl", mimeType: "image/png" }

プレースホルダーはオプションで maxBytes を指定できます。ホストは引き続きファイルサイズの上限と総量チェックを実行します。参照をファイルパスとして扱うことはできません。

ネイティブルートとホストプロトコル

ネイティブルート

meta.routesはプラグイン独自のURLを定義し、関数名は native オブジェクト内の同期関数を指します。

routes: [
  {
    method: 'POST',
    path: '/vendor/jobs',
    type: 'submit',
    decode: 'create',
    render: 'created',
  },
  {
    method: 'GET',
    path: '/vendor/jobs/:task_id',
    type: 'query',
    render: 'status',
  },
];

• submit / dynamic は decode と render を指定する必要があります。queryは render のみを指定し、デコーダを宣言することはできません。
• queryのタスクパラメータ名はデフォルトで task_id ですが、taskIdParam で指定できます。
• デコーダは { kind: "submit", model, action?, requestBody?, originTaskIds? } またはクエリインテントを返します。
• routes[].models はsubmit/dynamicのトップレベルモデルを制限できますが、queryには使用できません。モデルがベンダーボディ内にネストされている場合は、デコーダが判断すべきです。
• ホストは認証、所有権、タスクの永続化を担当し、レンダラーは外部応答のみを処理します。フックがスローするエラーメッセージは呼び出し元に返される可能性があるため、読みやすく機密データを含まないエラーテキストを使用すべきです。

originTaskIdsは公開タスクIDを使用します。ホストは所有権とチャネルの一貫性をチェックした後、内部アップストリームIDを含む originTasks をドライバーに注入します。これは外部レンダラーには渡されません。

ホストプロトコル

meta.protocolsはホストによって一元管理されるプロトコルパスを宣言します。これらのパスを meta.routes にコピーすべきではありません。

Responsesは、オブジェクト形式で supports を明示的に宣言する必要があります。stream は renderEvents を要求し、sync または background は renderFinal を要求します。必要なフックが不足している場合、または宣言されたパターンで使用されていないフックをエクスポートしている場合、いずれも拒否されます。

デコーダは候補のフィルタリングとチャネル選択後に複数回実行される可能性があるため、決定性を維持する必要があります。複数のプラグインが同じプロトコル下のモデルを共有できますが、実際のプラグインは選択されたチャネルによって決定されます。

ビデオレンダラーはJSONオブジェクトを返す必要があります。ホストは標準のID、モデル、ステータス、時間フィールドを上書きし、ルールに準拠するベンダー拡張を保持します。Responsesの成功結果は、ホストが注入する ctx.artifacts[key].url を介して成果物を参照します。

使用量フック

オプションで extractUsage、extractUsageOnSubmit、および extractUsageOnComplete をエクスポートできます。これらはそれぞれ、リクエスト、送信結果、または完了結果から使用量を抽出します。選択されたスキーマに合致する事実のみを返し、価格やクォータは返しません。

usageProfilesは、リストされたモデルに完全なスキーマを提供し、デフォルトの定義を置き換えます。一致しないモデルはデフォルトのスキーマを使用します。モデルマッピングが関与する場合、実行時には最終的に実行されるプラグインのアップストリームモデルに従って使用量定義が選択されます。設定については、使用量と課金を参照してください。

成果物とコンテンツリクエスト

成果物フックはペアでエクスポートする必要があります。

• listArtifacts(task)：永続化されたデータから安定した { key, type, mimeType? } のリストを投影します。2つ目の永続化レコードや一時的なダウンロードURLは返しません。
• buildContentRequest(ctx)：選択された成果物キー、データ、プロダクションバージョン、アップストリームタスクID、チャネル情報、および安全なRange/条件付きリクエストヘッダーに基づいて、今回の読み取り記述子を構築します。

チャネル資格情報付きのコンテンツリクエストは、チャネルホストまたは allowedHosts にのみアクセスできます。公開動的CDNは credentialless: true を使用できます。この場合、GET/HEADのみが許可され、プラグインヘッダーやボディを添付することはできません。ホストは初期アドレスとリダイレクトをチェックします。

ホストの成果物リンクは TaskPublicAddress を使用し、デフォルトでは ServerAddress にフォールバックします。マルチノードは有効な CRYPTO_SECRET を共有する必要があります。これをローテーションすると、発行済みのすべてのアドレスが無効になります。

即時完了、SSE、およびホスト機能

parseSubmitResponseは immediate 最終状態の結果を返すことができ、ホストが送信段階で永続化と決済を完了できるようにします。これらのタスクはポーリングを継続しません。

アップストリーム送信でSSEを使用する場合、submitResponseTypes: ["json", "sse"] を宣言し、記述子で responseType: "sse" を選択します。

SSEモードは、アップストリームイベントをクライアントに直接透過的に渡しません。プラグインはイベントのセマンティクスと終了条件を解釈し、ホストは接続、フレーム解析、サイズ制限、タイムアウトを管理します。アップストリームSSEの受け入れに成功した後の読み取り失敗は、自動的に送信を再試行せず、重複する課金タスクの作成を回避します。

json-clone@1 は、変更可能な独立したJSONスナップショットを作成するための同期的な utils.json.clone(value) を提供します。その他のツールには、時間、UUID、Base64、HMAC、JWT、およびVolc署名ツールが含まれます。完全なシグネチャは型宣言を参照してください。requiredCapabilities は正確なバージョンを宣言する必要があります。不明またはサポートされていない機能は、ロード時に拒否されます。

管理および診断インターフェース

ルート管理インターフェースは /api/plugin/task にあり、アップロード、バージョンアクティベーション、ステータス切り替え、削除、マーケットプレイスソース、ドライラン、および /runtime/status を含みます。これらの管理操作は、APIキーを使用してアクセスする /v1/tasks とは異なる権限体系です。

ランタイムは完全な世代としてアトミックに公開されます。リクエストは固定の世代を使用し、バックグラウンドポーリングは更新されたプラグインを使用する可能性があります。マルチノードのトラブルシューティングでは、データベースのオーバーライドリビジョンを比較すべきであり、各ノードの自動インクリメントされる世代番号を直接比較することはできません。

デバッグ手順については開発ガイドを、リリースチェックについては公開仕様を参照してください。