Bir aracı çağırma

Her yetenek tek bir araçtır ve hepsi aynı şekilde çağrılır: POST /v1/direct/tools/{tool_name}. Araç kataloğu hepsini listeler.

İstekCopy Anchor Link

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

Bir idempotency anahtarıyla eksiksiz bir çağrı:

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

YanıtCopy Anchor Link

Her başarılı yanıt aynı zarfa sahiptir. Aracın kendi çıktısı, output_schema şemasında tanımlandığı şekilde result içinde yer alır.

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

Faturalandırma bloğuCopy Anchor Link

billing, ücretsiz çağrılar dahil her başarılı yanıtta bulunur.

Blok, çağrının döndüğü anda ne kadar ücret aldığını bildirir. İadeler ve kesinleştirme daha sonra gerçekleşir ve orijinal yanıtta değil, üretimde görünür. Yanıtlar ayrıca ağ geçidinizde günlüğe yazmanız için Morphic-Credits-Charged: <integer> başlığını taşır. Krediler ve kullanım, bir üretimin nasıl ücretlendirildiğini, kesinleştirildiğini ve iade edildiğini açıklar.

Araç retleriCopy Anchor Link

Girdi doğru biçimde olduğu halde çalıştırılamadığında (planınızda olmayan bir model, modelin sunmadığı bir en boy oranı, yanlış türde bir varlık) çağrı 422 tool_refused yanıtını verir. Mesaj; alanı, değeri ve işe yarayacak değerleri belirtir. Hiçbir şey başlatılmamış ve hiçbir ücret alınmamıştır.

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

Kısmi başlatmalarCopy Anchor Link

variations değeri 1'den büyük olan bir çağrı, her varyasyon için bir üretim başlatır. Önceki varyasyonlar başladıktan sonra sonraki bir varyasyon reddedilirse:

• Yanıt yine 202 olur ve ne olduğunu result.partial_failure söyler.
• result.generation_ids yalnızca başlayanları listeler ve billing yalnızca başlayanları sayar.
• Yalnızca eksik varyasyonları yeniden deneyin.

IdempotencyCopy Anchor Link

Bir ağ hatası, istek gönderildikten sonra ve yanıtı gelmeden önce yaşanabilir. Ücretli bir çağrıyı güvenle yeniden denemek için bir Idempotency-Key başlığı gönderin. Kendi iş veya sipariş kimliğinizi kullanın.

Idempotency-Key: order-4411-hero-image

• Bir anahtarla yapılan ilk istek normal şekilde çalışır.
• Aynı anahtar, araç ve gövdeyle 24 saat içinde yapılan bir yeniden deneme tekrar çalışmaz. Orijinal generation_ids ve billing dahil orijinal yanıt gövdesiyle 200 döner ve ek ücret almaz. Morphic-Credits-Charged başlığı 0 olur.
• Aynı anahtar farklı bir araç veya gövdeyle kullanılırsa 409 idempotency_conflict döner.
• Orijinal istek hâlâ çalışırken yapılan bir yeniden deneme 409 idempotency_in_progress döner.
• Orijinali başarısız olan (5xx) ya da çalışmış olabileceği halde hiç yanıt vermeyen ücretli bir çağrının yeniden denemesi 409 idempotency_outcome_unknown döner. Aynı anahtarla asla yeniden çalıştırılmaz: sonucunu kontrol edin, ardından yeni bir anahtar kullanın.
• Anahtarlar, onları gönderen API anahtarına özgüdür ve en fazla 200 karakter olabilir.

Ücretsiz çağrılar da bu başlığı kabul eder, ancak nadiren ihtiyaç duyar.

5xx sonrasında ücretli bir çağrıyı yeniden denemeCopy Anchor Link

500, 503 veya 504 yanıtı veren ücretli bir çağrı, başarısız olmadan önce işi başlatmış ve ücretini almış olabilir.

1. Çağrının ne yaptığını list_generations ile veya zamana göre filtrelenmiş GET /v1/direct/usage ile kontrol edin.
2. Yalnızca başlamamış işler için yeni bir Idempotency-Key gönderin.

Hiç yanıt gelmediğinde (bağlantı koptuğunda) aynı anahtarla yeniden deneyin: saklanan yanıtı ya da istek hâlâ çalışıyorsa 409 idempotency_in_progress alırsınız.

Herhangi bir sorun yaşarsanız ya da sorularınız olursa, bizimle iletişime geçmekten çekinmeyin. Yardım etmeye memnuniyet duyarız. Bize şu adresten yazın: support@morphic.com.