コンテンツにスキップ

生成結果の取得

メソッド

この API は REST の方法論に従います。

HTTP メソッド

GET: 完了した生成の DesignSpec を読み取ります — プラグインが Figma へマテリアライズする文書です。

命名規則

レスポンスは内部の wf2des-api データプレーンから 逐語でプロキシ されるため、フィールドは行系エンドポイントで使われる camelCase ではなく snake_case です。形状はワーカーが所有します。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

  • Authorization
  • Accept
  • Accept-language

レスポンスヘッダー

  • Content-Type

結果の取得

URI

GET /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/{wf2des_id}/result

パスパラメータ

名前 型 必須 説明
organization_id integer 必須 組織 ID
project_id integer 必須 プロジェクト ID
wf2des_id string 必須 wf2des ID

レスポンス

レスポンスは JSON です（HTTP ステータス: 200 OK）。

{
  "wf2des_id": "wf2des-001",
  "spec": {
    "root": { "type": "frame", "children": [] },
    "spec_nodes_flat": []
  },
  "confidence": {
    "score": 0.82,
    "flag_count": 3
  },
  "artifact_urls": {
    "parse": "1/7/wf2des/wf2des-001/1-parse.json",
    "result": "1/7/wf2des/wf2des-001/1-result.json",
    "manifest": "1/7/wf2des/wf2des-001/1-manifest.json"
  }
}

レスポンスフィールド

名前 型 説明
wf2des_id string この結果が属する実行。
spec object | null プラグインがマテリアライズする DesignSpec — コンポーネント束縛を伴う組み立て済みノードツリー。
confidence object | null 実行の confidence ブロック。flag_count（レビュー対象としてフラグされたノード数）を含む。
artifact_urls object 実行のイミュータブルなアーティファクトの S3 キー（parse / result / manifest、およびスピル時の spec）。

大きな spec は呼び出し側から透過的です。 約 1 MB を超える spec は生成時に独立した S3 オブジェクトへスピルされ、文書外に保存されます。本エンドポイントはそれをインラインで読み戻し、同じフィールドに入れて返します。呼び出し側が見るのは常に中身の入った spec であり、辿るべきポインタではありません。

認証

認証は Amazon Cognito が発行する JSON Web Token（JWT）で行われます。加えて、呼び出し元はプロジェクトへのアクセス権を保持している必要があります。

エラーハンドリング

説明 ステータスコード ステータス名
認証情報の欠落 401 Unauthorized
権限不足 403 Forbidden
結果が見つからない（未知の wf2des_id、または実行がまだ生成していない） 404 Not Found
上流の読み取り失敗（wf2des-api または S3） 500 Internal Server Error

parse や assemble の途中の実行はここで 404 を返します — 結果文書は assemble が終端ブロックを書いた時点で初めて存在します。準備完了の判定には GET …/wf2des/{wf2des_id} で行をポーリングしてください。

処理フロー

  1. パスパラメータから組織 ID、プロジェクト ID、wf2des_id を取得する。
  2. ユーザーがプロジェクトへのアクセス権を持つことを検証する。
  3. 組織とプロジェクトにスコープした上で、内部 wf2des-api データプレーンへ読み取りをプロキシする（X-AI-Service-Token）。
  4. データプレーンは design_generation_result 文書を読み込み、spec が無くスピル済みの artifact_urls.spec がある場合はそのオブジェクトをインラインで読む。
  5. 文書を逐語で返す。