生成

生成は非同期処理の 1 単位です。1 枚の画像、1 本の動画、1 本の音声トラック、1 回のレンダリングがそれぞれ 1 件の生成にあたります。returns_generation: true のツールは 1 件以上の生成を開始し、その ID をすぐに返します。生成はポーリング、Webhook、またはその両方で追跡します。Webhook を主な通知手段とし、ときどきのポーリングを安全策として使ってください。

ステータスCopy Anchor Link

queued ──► in_progress ──► succeeded
   │             │
   │             ├──────► failed
   └─────────────┴──────► cancelled

認識できないステータスは最終状態ではないものとして扱い、生成の追跡を続けてください。新しい中間ステータスが追加される可能性があります。

生成オブジェクトCopy Anchor Link

{
  "object": "generation",
  "id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
  "tool": "generate_video",
  "status": "succeeded",
  "project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
  "model_id": "mdl_7rk2pq9vxa4m",
  "created_at": "2026-10-25T09:14:03.120Z",
  "completed_at": "2026-10-25T09:15:41.902Z",
  "error": null,
  "billing": {
    "estimated_credits": 120,
    "credits_charged": 96,
    "credits_refunded": 0,
    "credits_are_final": true,
    "credits_settle_on_output_duration": true
  },
  "assets": [
    {
      "id": "0192a7b4-0f1e-7d3c-9b8a-7c6d5e4f3a2b",
      "type": "video",
      "name": "Bicycle hero shot",
      "mime_type": "video/mp4",
      "width": 1920,
      "height": 1080,
      "duration_seconds": 8,
      "url": "https://mcp.morphic.com/m/Xk29dPq",
      "url_expires_at": null,
      "studio_url": "https://studio.morphic.com/…",
      "final_generation_expires_at": null
    }
  ],
  "content_left_out": [],
  "render_warnings": [],
  "metadata": { "order_id": "4411" },
  "poll_after_seconds": null
}

1 件の生成を読み取るCopy Anchor Link

GET /v1/direct/generations/{id} は { "generation": { … } } とともに 200 を返します。

curl -s "https://mcp.morphic.com/v1/direct/generations/$ID?wait=45" \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

• wait は任意で、0 から 45 秒です。生成のステータスが変わるか完了するまでリクエストが保持され、その時点ですぐに応答します。
• 待機時間が切れると、現在の状態を返します。45 を超える値は 45 に切り詰められます。
• 他の組織の生成や、このキーで読み取れない生成には、403 ではなく 404 が返ります。そのため ID を探られることはありません。

複数の生成を読み取るCopy Anchor Link

POST /v1/direct/generations/batch-get は、1 回のリクエストで最大 10 件の生成を読み取ります。

curl -s https://mcp.morphic.com/v1/direct/generations/batch-get \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["0192a7b3-…", "0192a7b3-…"], "wait": 30}'

• wait を指定すると、いずれかのステータスが変わるか、すべてが最終状態になった時点で応答します。
• レスポンスは { "generations": [ … ], "not_found": ["…"] } で、リクエストした順に並びます。

ポーリングの頻度Copy Anchor Link

各開始レスポンスと、最終状態でない各読み取りには poll_after_seconds が含まれます。次の読み取りまで少なくともその秒数だけ待ち、その後は間隔を延ばしてください。

ロングポーリング（wait=45）は、保持された時間にかかわらず 1 回の読み取りとしてカウントされるため、最も速く、最も負担の少ないポーリング方法です。HTTP クライアントのタイムアウトは待機時間より長く設定してください。wait=45 なら 60 秒です。

import time, requests

def wait_for(generation_id, key):
    headers = {"Authorization": f"Bearer {key}"}
    url = f"https://mcp.morphic.com/v1/direct/generations/{generation_id}"
    while True:
        r = requests.get(url, params={"wait": 45}, headers=headers, timeout=60)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        r.raise_for_status()
        gen = r.json()["generation"]
        if gen["status"] in ("succeeded", "failed", "cancelled"):
            return gen
        # A long-poll already waited; only sleep if the server asks for more.
        time.sleep(max(0, (gen.get("poll_after_seconds") or 0) - 45))

ポーリングの制限Copy Anchor Link

一括読み取りは、ID ごとに 1 回として両方の制限にカウントされます。推奨の間隔であれば、1 つのキーで同時に数百件の進行中の生成を追跡できます。それ以上を追跡する場合は Webhook を使ってください。

何かお困りのことやご質問がありましたら、お気軽にご連絡ください。喜んでお手伝いします。こちらまでご連絡ください support@morphic.com.