Memanggil alat

Setiap kemampuan adalah satu alat, dan semuanya dipanggil dengan cara yang sama: POST /v1/direct/tools/{tool_name}. Katalog alat mencantumkan semuanya.

PermintaanCopy Anchor Link

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

Panggilan lengkap, dengan kunci idempotensi:

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"}}'

ResponsCopy Anchor Link

Setiap respons sukses memiliki amplop yang sama. Keluaran alat itu sendiri ada di result, sesuai yang dijelaskan output_schema miliknya.

{
  "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"]
  }
}

Blok penagihanCopy Anchor Link

billing ada di setiap respons sukses, termasuk panggilan gratis.

Blok ini melaporkan apa yang ditagihkan panggilan saat ia kembali. Pengembalian kredit dan penyelesaian tagihan terjadi kemudian dan muncul pada generasi, tidak pernah pada respons awal. Respons juga membawa Morphic-Credits-Charged: <integer> untuk pencatatan di gateway Anda. Kredit dan pemakaian menjelaskan bagaimana generasi ditagih, diselesaikan, dan dikembalikan kreditnya.

Penolakan alatCopy Anchor Link

Ketika input berbentuk benar tetapi tidak dapat dijalankan (model yang tidak ada di paket Anda, rasio aspek yang tidak ditawarkan model, aset dengan jenis yang salah), panggilan dijawab dengan 422 tool_refused. Pesannya menyebutkan field, nilainya, dan nilai yang akan berhasil. Tidak ada yang dimulai dan tidak ada yang ditagihkan.

{
  "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. …" }
}

Permulaan sebagianCopy Anchor Link

Panggilan dengan variations di atas 1 memulai satu generasi per variasi. Jika variasi berikutnya ditolak setelah variasi sebelumnya sudah dimulai:

• Respons tetap 202, dan result.partial_failure menjelaskan apa yang terjadi.
• result.generation_ids hanya mencantumkan yang sudah dimulai, dan billing hanya menghitung yang sudah dimulai.
• Ulangi hanya variasi yang belum ada.

IdempotensiCopy Anchor Link

Kegagalan jaringan dapat terjadi setelah permintaan terkirim dan sebelum jawabannya tiba. Untuk mengulangi panggilan berbayar dengan aman, kirim header Idempotency-Key. Gunakan id pekerjaan atau id pesanan Anda sendiri.

Idempotency-Key: order-4411-hero-image

• Permintaan pertama dengan sebuah kunci berjalan seperti biasa.
• Pengulangan dengan kunci, alat, dan body yang sama dalam 24 jam tidak dijalankan lagi. Pengulangan itu menjawab 200 dengan body respons asli, termasuk generation_ids dan billing asli, dan tidak menagih apa pun lagi. Header Morphic-Credits-Charged miliknya bernilai 0.
• Kunci yang sama dengan alat atau body yang berbeda dijawab dengan 409 idempotency_conflict.
• Pengulangan saat permintaan asli masih berjalan dijawab dengan 409 idempotency_in_progress.
• Pengulangan panggilan berbayar yang aslinya gagal (5xx) atau tidak pernah menjawab setelah mungkin sudah berjalan dijawab dengan 409 idempotency_outcome_unknown. Panggilan itu tidak pernah dijalankan lagi dengan kunci yang sama: periksa hasilnya, lalu gunakan kunci baru.
• Kunci berlaku untuk kunci API yang mengirimnya, dengan panjang hingga 200 karakter.

Panggilan gratis juga menerima header ini, tetapi jarang membutuhkannya.

Mengulangi panggilan berbayar setelah 5xxCopy Anchor Link

Panggilan berbayar yang menjawab 500, 503, atau 504 mungkin sudah memulai pekerjaan dan menagihnya sebelum gagal.

1. Periksa apa yang dilakukan panggilan itu dengan list_generations, atau dengan GET /v1/direct/usage yang difilter berdasarkan waktu.
2. Kirim Idempotency-Key baru hanya untuk pekerjaan yang belum dimulai.

Jika tidak ada jawaban sama sekali (koneksi terputus), ulangi dengan kunci yang sama: Anda mendapatkan jawaban yang tersimpan, atau 409 idempotency_in_progress selama panggilan itu masih berjalan.

Jika Anda mengalami kendala atau memiliki pertanyaan, jangan ragu untuk menghubungi kami. Kami dengan senang hati akan membantu. Tulis kepada kami di support@morphic.com.