ツールの実行
アクションを送信してから最終的な出力を受け取るまでに起きることを理解します。
入力を確認する
正確なツールIDと現在の入力スキーマを使います。GET /tools/definition/{name}は、入力スキーマ・例・プロバイダー・モデル・料金を含むツールを1つ返します。アプリのカタログにも同じ内容が表示されます。
available: falseのツール・プロバイダー・モデルは、まだこのプロジェクトで実行できません。理由はunavailableにあり、own_key（自分のプロバイダーキーが要る）、connection（アプリの接続が要る）、permission（接続に必要な権限がない）、setup（Relvo側の準備が終わっていない）、retired（提供終了）のどれかです。まずは、必要な情報が返るかどうかを確かめられる小さなリクエストから始めます。
実行を追う
すぐに終わるツールもあれば、実行ID付きで受け付けだけを返すツールもあります。そのIDを控え、ステータスがqueued・running・waitingでなくなるまで実行を読みます。
queued
受け付け済みで、開始を待っています。
running
プロバイダーが処理しています。
waiting
プロバイダーの非同期ジョブを待っています。
succeeded
完了。outputに結果があります。
failed
errorCodeで終了。部分的な出力や請求が残る場合があります。
cancelled
キャンセル要求、期限切れ、キーの権限の喪失で停止（errorCodeはplatform_execution_cancelled）、または接続のルールで停止（platform_approval_requiredかplatform_connection_policy_denied）。すでにかかった費用は請求されます。
needs_review
プロバイダーの請求が見積もりを超えたか、確認できませんでした。Relvoが確認するまで予約を保持します。クライアント側のタイムアウトだけでは、ツールが動いたかどうかは分かりません。同じ有料の、または状態を変える作業を再送する前に、既存の実行を確認してください。
出力を読む
outputはJSONオブジェクトで、フィールドはツール・プロバイダー・モードによって変わります。ツールごとの出力スキーマはありません。成功した呼び出しでもdata: nullやfound: falseを返すことがあります。成功したプロバイダーへのリクエストが1回ならoutputはそのオブジェクト、それ以外は成功したリクエストごとに1件ずつ並ぶ{ "results": [{ "step": 0, "data": … }] }です。
大きな結果では、GET /tools/executions/{id}/contextが要約を返し、POST /tools/executions/{id}/resultがパスで指定した一部をoffset・limit・maxChars付きで読みます。
ファイルと成果物
手元の画像・音声・動画をツールに渡すには、先にアップロードします。POST /tools/uploadはmimeTypeとbase64のdata（12 MiBまで）を受け取り、ツールの引数に使うf_…のファイルIDを返します。アップロードには、購入した残高か、プロジェクトに保存した自分のプロバイダーキーが必要です。1チームが24時間にアップロードできるのは1 GiBまでで、ファイルは30日で期限切れになります。
生成された画像・音声・動画は、a_…のIDを持つ成果物としてoutputに入ります。ダウンロードのリンクは最長5分有効で、成果物は30日間保存され、それぞれ24時間に10回までダウンロードのリンクを発行できます。
失敗したリクエストを扱う
エラーを読み、入力・アクセス・割り当て・プロバイダーのどれに関する問題かを特定します。原因を直してから再試行してください。failed・cancelled・needs_reviewの実行は、理由をerrorCodeで返します。
サポートに問い合わせるときは、ツールID、実行ID、エラーメッセージを控えます。よくある確認事項はトラブルシューティングにまとめています。
実行をキャンセルする
POST /tools/executions/{id}/cancelは進行中の実行に停止を求め、cancelRequested: trueを付けた今の状態を返します。すでに始まった処理は完了する場合があり、かかった費用は請求されます。キャンセルできるのは、送信したメンバーかプロジェクト管理者だけです。