ツールの呼び出し

各機能は 1 つのツールであり、すべて同じ方法で呼び出します: POST /v1/direct/tools/{tool_name}。すべてのツールは ツールカタログ に掲載しています。

リクエストCopy Anchor Link

{
  "input": { },
  "webhook_id": "01929a10-0c3d-7f44-8a21-0b1c2d3e4f50",
  "metadata": { "order_id": "4411", "customer": "acme" }
}

冪等性キーを付けた完全な呼び出しの例:

curl -s https://mcp.morphic.com/v1/direct/tools/generate_image \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4411-hero-image" \
  -d '{"input": {"prompt": "A red vintage bicycle against a pastel wall", "project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f"}, "metadata": {"order_id": "4411"}}'

レスポンスCopy Anchor Link

成功時のレスポンスは、すべて同じ形式です。ツール自体の出力は、その output_schema が示す形で result に入ります。

{
  "request_id": "0192a7b3-91d0-7c55-b1aa-6e5f4c3b2a10",
  "tool": "generate_image",
  "result": {
    "generation_id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
    "generation_ids": ["0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f"],
    "status": "queued",
    "project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
    "project_name": "Spring campaign",
    "file_id": "01928f4e-6c8d-7a10-b2c3-d4e5f6a7b8c9",
    "model_id": "mdl_3hv8tq1nzc6e",
    "estimated_credits": 8,
    "credits_settle_on_output_duration": false
  },
  "billing": {
    "credits_charged": 8,
    "credits_are_final": false,
    "credits_settle_on_output_duration": false,
    "generation_ids": ["0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f"]
  }
}

課金ブロックCopy Anchor Link

billing は、無料の呼び出しを含むすべての成功レスポンスに含まれます。

このブロックは、呼び出しが返った時点での請求額を示します。返金と精算はその後に行われ、元のレスポンスではなく生成に反映されます。レスポンスには、ゲートウェイでのログ記録用に Morphic-Credits-Charged: <integer> も含まれます。生成の請求、精算、返金の仕組みは クレジットと使用量 で説明しています。

ツールの拒否Copy Anchor Link

入力の形式は正しいものの実行できない場合（プランに含まれないモデル、モデルが対応していないアスペクト比、種類の異なるアセットなど）、呼び出しは 422 tool_refused を返します。メッセージには、フィールド、値、受け付けられる値が示されます。何も開始されず、請求も発生しません。

{
  "description": "aspect_ratio: \"21:9\" is not offered by model mdl_3hv8tq1nzc6e. Offered: 1:1, 4:3, 3:4, 16:9, 9:16. Models offering 21:9 for text_to_image: mdl_9wd4mf2kqs7b.",
  "code": "tool_refused",
  "data": { "request_id": "0192a7b3-…", "tool": "generate_image" },
  "error": { "error_code": "TOOL_REFUSED", "message": "aspect_ratio: \"21:9\" is not offered by model mdl_3hv8tq1nzc6e. …" }
}

一部のみの開始Copy Anchor Link

variations が 1 より大きい呼び出しは、バリエーションごとに 1 件の生成を開始します。先のバリエーションが開始された後で、後のバリエーションが拒否された場合:

• レスポンスは 202 のままで、result.partial_failure に何が起きたかが示されます。
• result.generation_ids には開始されたものだけが含まれ、billing も開始されたものだけをカウントします。
• 欠けたバリエーションだけを再試行してください。

冪等性Copy Anchor Link

ネットワーク障害は、リクエストが送信された後、応答が届く前に起きることがあります。有料の呼び出しを安全に再試行するには、Idempotency-Key ヘッダーを送信します。お客様自身のジョブ ID や注文 ID を使ってください。

Idempotency-Key: order-4411-hero-image

• あるキーでの最初のリクエストは通常どおり実行されます。
• 24 時間以内に同じキー、同じツール、同じボディで再試行しても、再実行はされません。元のレスポンスボディ（元の generation_ids と billing を含む）とともに 200 を返し、追加の請求はありません。その Morphic-Credits-Charged ヘッダーは 0 です。
• 同じキーで異なるツールまたはボディを送ると、409 idempotency_conflict が返ります。
• 元のリクエストがまだ実行中に再試行すると、409 idempotency_in_progress が返ります。
• 元のリクエストが失敗した（5xx）、または実行された可能性がある状態で応答しなかった有料の呼び出しを再試行すると、409 idempotency_outcome_unknown が返ります。同じキーで再実行されることはありません。結果を確認してから、新しいキーを使ってください。
• キーは送信した API キーごとに区別され、最大 200 文字です。

無料の呼び出しもこのヘッダーを受け付けますが、必要になることはほとんどありません。

5xx の後に有料の呼び出しを再試行するCopy Anchor Link

500、503、504 を返した有料の呼び出しは、失敗する前に作業を開始し、請求している可能性があります。

1. 呼び出しが何をしたかを、list_generations または時間で絞り込んだ GET /v1/direct/usage で確認します。
2. 開始されなかった作業についてのみ、新しい Idempotency-Key で送信します。

応答がまったく届かなかった場合（接続の切断）は、同じキーで再試行してください。保存された応答が返るか、まだ実行中であれば 409 idempotency_in_progress が返ります。

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