呼び出しガイド

インスタンスのAPIキーを使用してタスクを送信し、ステータスを照会し、アーティファクトを読み取る方法、およびプラグインのネイティブルーティングとVideo、Responsesプロトコルについて学びます。

呼び出し前の確認

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

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

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

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

メソッド	パス	役割
POST	`/v1/tasks/{pluginKey}`	タスクの送信
GET	`/v1/tasks/{taskId}`	自身のタスクの照会
GET	`/v1/tasks/{taskId}/artifacts`	タスクアーティファクトのリスト表示
GET / HEAD	`/v1/tasks/{taskId}/artifacts/{artifactKey}/content`	アーティファクト内容の読み取りまたは確認

タスクの送信

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 のみを含むリクエストを受け入れるわけではありません。

共通の送信応答には、New APIによって生成された公開タスク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

アーティファクトアドレス

content_url には、ホストが発行したアクセス認証情報が含まれている場合があります。このリンクを保持している人は、対応するアーティファクトを読み取ることができます。機密リンクとして管理してください。リンクの発行はインスタンスの公開アドレスとキー設定に依存します。詳細はよくある質問を参照してください。

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

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

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

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 を宣言するプラグインは、サポートするリクエストモードを明確に公開します。

モード	リクエストパラメータ	動作
`sync`	`stream` / `background` を設定しない	タスクの最終状態を待って結果を返す
`stream`	`stream: true`	ホストが管理するSSE応答を使用する
`background`	`background: true`	最初に処理中のResponseを返し、その後照会する

以下に、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送信インターフェースを採用しているからといって、アップストリームイベントが直接クライアントにパススルーされるわけではありません。

目次