呼び出しガイド

呼び出し前の確認

管理者はまずプラグインのインストール、チャネルの設定、価格の設定を行う必要があります。呼び出し元は自身のModelRouterインスタンスのAPIキーを使用し、そのキーが対応するモデルとグループにアクセスできることを確認してください。

このページに記載されている https://your-newapi.example はインスタンスアドレスのプレースホルダーであり、公式サイトではありません。公式サイトはプラグインの閲覧とダウンロードに使用されます。実際の生成リクエストは、設定したインスタンスに送信されます。

プラグインマーケットの詳細で、プラグインがサポートするエンドポイントとモデルを確認してください。すべてのプラグインが以下にリストされているすべてのプロトコルをサポートしているわけではありません。

共通タスクインターフェース

タスクの送信

curl 'https://your-newapi.example/v1/tasks/<plugin-key>' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<model>",
    "prompt": "一只小猫在窗边看雨"
  }'

<plugin-key>、<model>、<NEW_API_KEY> を置き換えてください。model は必須項目であり、その他のフィールドは選択したプラグインのリクエスト構築ロジックによって決定されます。上記はリクエスト構造の例であり、特定のプラグインでは画像、動画、期間、その他のフィールドが要求される場合があります。すべてのプラグインが prompt のみを含むリクエストを受け入れるわけではありません。

共通の送信応答には、 ModelRouterによって生成された公開タスクIDが含まれます。例：

{
  "id": "<public-task-id>",
  "task_id": "<public-task-id>",
  "status": "queued",
  "model": "<model>",
  "created_at": 1780000000
}

返された task_id を保存してください。後続の照会では、アップストリームベンダーから返された内部タスクIDではなく、この公開IDを使用します。

ステータスの照会

curl 'https://your-newapi.example/v1/tasks/<public-task-id>' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

照会応答には、task_id、platform、status、progress、fail_reason、created_at、finished_at が直接含まれます。タスクは NOT_START、SUBMITTED、QUEUED、IN_PROGRESS を経て、最終的に SUCCESS または FAILURE に移行する可能性があります。

適切な間隔で照会し、最終状態になったらポーリングを停止してください。共通の照会応答が元のアップストリームペイロードやアーティファクトURLを返すとは限りません。失敗の原因は fail_reason を参照し、必要に応じてインスタンス管理者にタスクログの確認を依頼してください。

アーティファクトの取得

curl 'https://your-newapi.example/v1/tasks/<public-task-id>/artifacts' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

プラグインがアーティファクトをサポートしている場合、応答の artifacts 配列には、安定した key、type、オプションの mime_type、および content_url が含まれます。すべてのプラグインが video を使用すると仮定せず、実際に返されたキーを使用してください。

返された content_url を読み取ることも、APIキー付きのコンテンツインターフェースを介してダウンロードすることもできます。

curl 'https://your-newapi.example/v1/tasks/<public-task-id>/artifacts/<artifact-key>/content' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  --output result.bin

プラグインネイティブルーティング

プラグインは meta.routes を介してベンダー形式のネイティブインターフェースを提供できます。マーケット詳細に記載されている実際のパス、HTTPメソッド、リクエスト構造を使用し、引き続き自身のModelRouterインスタンスにリクエストを送信し、インスタンスAPIキーを提供します。

ネイティブルーティングの応答のラッピングはプラグインによって決定されるため、上記の共通タスク応答フィールドをすべてのネイティブインターフェースに直接適用することはできません。照会ルーティングは、ホストが最初にタスクの所有権を検証します。送信および動的ルーティングは、宣言に基づいてモデル範囲もチェックします。

ネイティブパスには /doubao/api/v3/... や /ali/api/v1/... のようなプラグイン固有のプレフィックスが含まれる場合があります。ベンダーのパスを確認せずそのままゲートウェイに使わないでください。retainResult: false を宣言する即時完了ルートでは作成応答の結果を保存します。その後の結果照会や成果物取得は利用できませんが、課金とタスクログは残ります。

OpenAI Image 互換インターフェース

openai_image を宣言するプラグインは対応モデルの画像生成と編集を処理できます。どちらも現在のリクエスト内で結果を待ち、画像プロトコルでポーリングするためのタスクハンドルは返しません。Responses の stream / sync / background モードも宣言しません。生成は JSON、編集は JSON または multipart を使い、具体的なフィールドはプラグインによって決まります。

curl 'https://your-newapi.example/v1/images/generations' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<supported-image-model>",
    "prompt": "窓辺にいる子猫",
    "n": 1,
    "response_format": "b64_json"
  }'

curl 'https://your-newapi.example/v1/images/edits' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  --form-string 'model=<supported-image-model>' \
  -F 'prompt=2 枚の参照画像を組み合わせてイラストを作成' \
  -F 'image[]=@reference-1.png' \
  -F 'image[]=@reference-2.png'

モデル名、キー、ローカル画像のパスを置き換えてください。繰り返しの image[] はプラグインとモデルが複数画像の編集に対応する場合にのみ使用します。multipart の Content-Type と boundary は curl に生成させます。

成功応答には created と data が含まれ、画像要素は url、b64_json、任意の revised_prompt を持ちます。response_format: "b64_json" ではホストが画像を取得して Base64 を追加します。取得失敗時には URL のみが残る場合もあるため、クライアント側で対応してください。

上流が非同期の場合、ホストがリクエスト内でポーリングします。TASK_PLUGIN_PROTOCOL_TIMEOUT_SECONDS（既定 600 秒）を超えると 504 task_timeout、タスク失敗時は理由とともに 400 を返します。切断やタイムアウトで送信済みタスクは取り消されず、バックグラウンド処理と精算が続きます。再送前にタスクログを確認してください。

即時終端の画像結果は後から取得するために保持されないので、応答から画像を保存してください。リクエスト内のポーリングで完了したタスクは保存済みスナップショットを保持しますが、Image プロトコル自体には画像照会エンドポイントはありません。

OpenAI Video互換インターフェース

openai_video を宣言するプラグインのみがこのプロトコルのルーティングに参加します。

curl 'https://your-newapi.example/v1/videos' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<supported-video-model>",
    "prompt": "海边日出，缓慢向前移动的镜头"
  }'

curl 'https://your-newapi.example/v1/videos/<video-id>' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

プロトコルエントリはJSONまたはmultipartをサポートしますが、具体的なフィールドと形式はプラグインのデコードロジックに依存します。アーティファクトコンテンツインターフェースは GET /v1/videos/{video-id}/content であり、HEADもサポートします。

Video照会は、プラグインが提供する拡張フィールドを保持できます。標準のID、モデル、ステータス、および時間フィールドはホストによって統一的に投影されます。照会は保存されたタスクスナップショットを読み取るものであり、毎回リアルタイムでアップストリームを照会するわけではありません。

Responses互換インターフェース

openai_responses を宣言するプラグインは、サポートするリクエストモードを明確に公開します。

以下に、background をサポートするプラグインの例を示します。

curl 'https://your-newapi.example/v1/responses' \
  -H 'Authorization: Bearer <NEW_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<supported-responses-model>",
    "input": "生成一幅山间日出的插画",
    "background": true
  }'

curl 'https://your-newapi.example/v1/responses/<response-id>' \
  -H 'Authorization: Bearer <NEW_API_KEY>'

リクエスト内容は、そのプラグインの decodeRequest の約束に準拠している必要があります。宣言されていないモードはチャネル選択段階で拒否され、すべてResponsesプロトコルに属しているからといって、自動的にストリーミングまたはバックグラウンド機能が得られるわけではありません。作成されたResponseの照会は独立した操作であり、4番目のモードではありません。

Responsesのメディアアーティファクトは、ホストが生成したアーティファクトアドレスを使用します。アップストリームがSSE送信インターフェースを採用しているからといって、アップストリームイベントが直接クライアントにパススルーされるわけではありません。