Skip to main content
Agent API を使うと、独自のアプリケーションから Krea Agent にタスクを渡せます。リクエストとレスポンスでは camelCase の JSON フィールドを使用します。Agent はバックグラウンドで作業し、その間にアプリケーションが進捗と結果を読み取ります。
Agent はバックグラウンドで作業します。質問はせず、コストや権限の確認は自動的に承認されます。すべての要件と制約をプロンプトに含めてください。送信前にタスクの内容を確認してください。

認証、アクセス、請求

https://api.krea.ai へのすべてのリクエストに Authorization: Bearer KREA_API_KEY を付けて送信します。個人用、サービス用、レガシーの API キーは、標準の 公開 API 認証 を使用します。 読み取りや継続ができるのは、認証されたワークスペース内で、認証された呼び出し元が所有するセッションのみです。セッション ID を知っていてもアクセス権は付与されません。Krea のファイル添付も、そのワークスペース内でその呼び出し元がアクセスできるものである必要があります。
Agent のターンはワークスペースの compute units 残高を使用します。API 残高は使用しません。Agent プランの利用権限と Free プランのメッセージ上限は引き続き適用されます。Agent のプラン、アクセス、クレジット を参照してください。
各レスポンスには url が含まれており、適切なアカウントとワークスペースのアクセス権があれば、Krea アプリでセッションを開くことができます。

セッションを開始して結果を待つ

まず環境変数に KREA_API_KEY を設定します。curl と jq を使う Bash、requests を使う Python、または組み込みの fetch か Krea SDK を使う Node.js から選んでください。
1

最初のターンを送信する

セッションを作成するには sessionId を省略します。返された sessionId と runId を保存してください。レスポンスは status: "running" で即座に返されます。
2

このターンを待つ

両方の ID を wait-for-session に渡します。timedOut が true の場合は、同じ ID で再度呼び出してください。タイムアウトしてもターンはキャンセルされません。
3

結果を読み取る

finished が true になったら status を確認します。text、media、および error があればそれを確認するか、返された url を開いてください。
Python の場合は pip install requests で requests をインストールしてください。Node.js の場合は Node.js 22 以降を使用し、サンプルを example.mjs として保存してください。SDK のサンプルには npm install @krea-ai/sdk が必要で、HTTP エンドポイントの呼び出しに requestRaw を使用します。 これらのサンプルは 1 件のメッセージを送信し、最大 5 分間待機します。HTTP エラー、および失敗またはキャンセルされたターンでは停止します。送信を自動的にリトライすることはありません。送信リクエストがタイムアウトした場合は、再送信する前に Krea でセッションを確認してください。最初のリクエストでターンが開始されている可能性があります。 待機時間の上限に達しても、ターンはバックグラウンドで継続します。出力されたセッション ID と実行 ID を保存しておけば、後で待機を再開できます。 timeoutSeconds は 1 から 300 までの整数で、デフォルトは 60 です。HTTP クライアントのタイムアウトは、リクエストする待機時間より長く設定してください。送信後に待機するときは、前のターンの終了ステータスを新しいターンのものと取り違えないよう、常に最新の runId を渡してください。

待機せずに読み取る

GET /agent/session/{sessionId} を使うと、現在のセッションのスナップショットを取得できます。
cURL

セッションを継続する

ターンが完了したら、その sessionId を指定して別のメッセージを送信します。
cURL
1 つのセッションで同時に実行できるターンは 1 つだけです。ターンの実行中に別のメッセージを送信すると、code: "conflict" とともに 409 が返されます。

入力と添付ファイル

send-message は次のフィールドを受け付けます。モデルの enum とスキーマの全体については リファレンス を参照してください。 添付ファイルの url には、アクセス可能な HTTP(S) URL、または file:550e8400-e29b-41d4-a716-446655440000 のような認可済みの Krea Files URI を指定できます。任意の name と contentType は、前後の空白が除去された、空でない最大 255 文字の文字列です。呼び出し元のローカルパスや OpenAI の file_ ID はサポートされていません。先に実際のファイルを転送してください。プロンプトのテキストに ID を書いても、その内容は転送されません。 Agent はアプリケーション側の会話や添付ファイルを引き継ぎません。他の方法ではアクセスできない参照ファイルは添付してください。プロンプト内、既存の Krea コンテキスト、または以前のセッションファイルにある利用可能な URL を繰り返し指定する必要はありません。

セッションの結果

send-message は sessionId、threadId、runId、status(常に "running")、url を返します。 GET /agent/session/{sessionId} と wait-for-session は、次のセッションビューを返します。必須の timedOut フィールドが追加されるのは wait-for-session のみです。 各 media 項目は、生成物(jobId と任意の mediaKind: image、video、audio、3d)、再ホストされたメディア(url と任意の mimeType)、または Krea ファイル(uri、name、mimeType)のいずれかを表します。生成物の詳細は GET /jobs/{jobId} で取得してください。Krea ファイルの URI は添付ファイルとして再利用できます。また、セッションの url を開いてファイルを表示することもできます。メディアはターンの実行中にも表示されることがあります。

エラー

エンドポイントのエラーは { "error": "...", "code": "...", "allowedModels": ["..."] } の形式です。必須なのは error のみです。送信後に失敗したターンは、代わりに成功したセッションレスポンス内で status: "failed" として表示されます。