タスクプラグイン 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 を省略した場合、元の状態が保持されます。明示的に返された場合にのみ更新されます。リクエストとステータス入力は読み取り専用と見なすべきであり、モジュールグローバル変数にタスクデータを保存することに依存すべきではありません。

上流種別とゲートウェイ間接続

meta.upstreams には重複しない vendor と new_api を指定できます。すべてのプラグインは暗黙に vendor に対応し、new_api は同じプラグインを導入した上流 ModelRouter ゲートウェイへの対応を示します。タイプ 60 は setting.task_plugin_key / setting.task_extend_plugin_keys でプラグインを紐付けます。channelTypes に 60 と 61 は指定できず、各従来型チャネルの所有権は引き続き単一プラグインに限られます。

ホストは DriverContext、TaskQueryContext、BatchQueryContext、buildContentRequest のコンテキストに { kind: "vendor" } または { kind: "new_api" } の ctx.upstream を渡します。フィールドがない場合は vendor として扱います。new_api ではベンダーのパスをそのまま使わず、/doubao/api/v3/... や /ali/api/v1/... など、プラグイン自身のネイティブパスを構築します。既にパスが一致する場合やホストプロトコルのみを使う場合、プレフィックスの変更は不要です。

タイプ 60 では、ホストが authHeader を Bearer <channel key>、apiKey をチャネルキーに設定済みで、ベンダーの OAuth/JWT 認証処理は実行しません。送信結果の解析は上流プラグインのネイティブ応答に対応し、照会にはそのゲートウェイが返す公開タスク ID を使います。upstreams は API v1 の追加拡張です。古いホストは未知のフィールドを拒否するため、導入前にホストを更新してください。

HTTP記述子とファイル

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

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

type RequestBody =
  | { kind: 'json'; value: unknown }
  | { kind: 'form'; fields: Record<string, readonly string[]> }
  | {
      kind: 'multipart';
      fields: Record<string, readonly string[]>;
      files: readonly FileReference[];
    }
  | { 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 を指定できます。ホストは引き続きファイルサイズの上限と総量チェックを実行します。参照をファイルパスとして扱うことはできません。

同じフィールド（例：image[]）に複数のファイルを送信できます。各ファイルの ref は独立しており、最初は request_file:<field>、以降は request_file:<field>#<index> です（0 起点なので 2 番目は #1）。parts[].fileRef や JSON プレースホルダーには対応する files[].ref をそのまま使い、手作業で参照を組み立てたり、同じフィールドの複数ファイルを一つの参照にまとめたりしないでください。

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

ネイティブルート

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 をドライバーに注入します。これは外部レンダラーには渡されません。

結果の保持

routes[].retainResult は submit/dynamic ルートの任意の真偽値で、既定値は true です。query ルートには指定できません。成功する送信がすべて即時完了する場合のみ false にします。即時終端結果では task.data を永続化せず、その後のネイティブ照会、Responses/Video 取得、成果物一覧・コンテンツ取得ではタスクが見つかりません。課金とログ用のタスク記録は残り、送信プレゼンターはメモリ内の完全なデータを受け取ります。完了時の使用量フックもデータ破棄前に実行されます。

false を宣言したルートが非同期タスクを返した場合、ホストは結果を保持して警告を記録します。Responses と Video は常に結果を保持します。Image の即時終端結果は作成応答に直接含まれ、結果データは保持されませんが、リクエスト内のポーリングで完了した結果は保存済みスナップショットを保持します。破棄済み結果を参照する場合、originTasks[].data は null です。古いホストは retainResult を拒否します。

ホストプロトコル

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

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

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

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

OpenAI Image プロトコル

"openai_image" または { name: "openai_image", models: [...] } を宣言し、supports は指定しません。openai_video と同様にリクエストモードはなく、どちらも文字列またはモデル制限付きのオブジェクトで宣言できます。生成は JSON、編集は JSON または multipart を受け付けます。ホストは ctx.model を固定し、ctx.operation: "generate" | "edit" を渡します。

decodeRequest と render を実装します。同期上流は parseSubmitResponse から終端の immediate を返します。非同期上流はタスク ID を返し、ホストがクライアントのリクエスト内で通常の照会フックを使って完了を待ちます。TASK_PLUGIN_PROTOCOL_TIMEOUT_SECONDS の既定値は 600 秒で、超過すると 504 task_timeout を返します。タイムアウトやクライアント切断後も、送信済みタスクはバックグラウンドで完了・精算されます。終端失敗は理由とともに 400 を返します。

成功時の render(ctx, task) は data 配列を持つオブジェクトを返します。各要素は { url } または { b64_json } で、revised_prompt を追加できます。ホストは未指定の created を補います。response_format: "b64_json" では画像 URL を取得して Base64 を追加し、元の URL も保持します。取得に失敗した場合は警告を記録し、URL を残します。このフックに ctx.artifacts は渡されず、画像 URL は上流結果から取得します。

使用量フック

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

usageProfiles はモデルごとの完全なスキーマと例を提供し、既定値とのマージや継承は行いません。実行時は最終的な上流モデルを優先します。その名前に profile がない場合（ベンダーのエンドポイント ID にマッピングされた場合など）はクライアント側モデルに、さらにプラグインの既定値にフォールバックします。保存済み価格は自動移行されません。詳しくは使用量と課金を参照してください。

数値フィールドの description は課金対象と単価を表す名称（例：Image generation unit price / 图片生成单价）にします。実際の値は引き続き使用量です。単位は unit、個数の表示単位は unitLabel、列挙値の表示名は enumLabels に入れます。動作・真偽値・列挙型の説明はそれぞれ動作、true が表す状態、条件を示します。翻訳は同じ意味とし、具体的な価格、プロトコルの詳細、文末の句読点を含めません。

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

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

• 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 とは異なる権限体系です。

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

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