Ein Tool aufrufen

Jede Funktion ist ein Tool, und alle werden gleich aufgerufen: POST /v1/direct/tools/{tool_name}. Der Tool-Katalog listet sie alle auf.

AnfrageCopy Anchor Link

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

Ein vollständiger Aufruf mit einem Idempotency-Key:

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

AntwortCopy Anchor Link

Jede erfolgreiche Antwort hat denselben Rahmen. Die eigentliche Ausgabe des Tools steht in result, wie sein output_schema sie beschreibt.

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

AbrechnungsblockCopy Anchor Link

billing ist in jeder erfolgreichen Antwort enthalten, auch bei kostenlosen Aufrufen.

Der Block meldet, was der Aufruf zum Zeitpunkt seiner Antwort berechnet hat. Rückerstattungen und die endgültige Abrechnung erfolgen später und erscheinen an der Generierung, nie in der ursprünglichen Antwort. Antworten enthalten außerdem Morphic-Credits-Charged: <integer> für die Protokollierung an Ihrem Gateway. Credits und Nutzung erklärt, wie eine Generierung berechnet, abgerechnet und erstattet wird.

Ablehnungen durch ein ToolCopy Anchor Link

Wenn die Eingabe korrekt aufgebaut ist, aber nicht ausgeführt werden kann (ein Modell, das Ihr Tarif nicht enthält, ein Seitenverhältnis, das das Modell nicht anbietet, ein Asset des falschen Typs), antwortet der Aufruf mit 422 tool_refused. Die Meldung nennt das Feld, den Wert und die Werte, die funktioniert hätten. Es wurde nichts gestartet und nichts berechnet.

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

Teilweise StartsCopy Anchor Link

Ein Aufruf mit variations über 1 startet eine Generierung pro Variante. Wird eine spätere Variante abgelehnt, nachdem frühere bereits gestartet sind:

• Die Antwort ist trotzdem 202, und result.partial_failure beschreibt, was passiert ist.
• result.generation_ids listet nur, was gestartet wurde, und billing zählt nur, was gestartet wurde.
• Wiederholen Sie nur die fehlenden Varianten.

IdempotenzCopy Anchor Link

Ein Netzwerkfehler kann auftreten, nachdem eine Anfrage gesendet wurde und bevor ihre Antwort eingetroffen ist. Um einen kostenpflichtigen Aufruf sicher zu wiederholen, senden Sie einen Idempotency-Key-Header. Verwenden Sie dafür Ihre eigene Job- oder Bestell-ID.

Idempotency-Key: order-4411-hero-image

• Die erste Anfrage mit einem Idempotency-Key wird normal ausgeführt.
• Eine Wiederholung mit demselben Idempotency-Key, demselben Tool und demselben Body innerhalb von 24 Stunden wird nicht erneut ausgeführt. Sie antwortet mit 200 und dem ursprünglichen Antwort-Body, einschließlich der ursprünglichen generation_ids und billing, und berechnet nichts weiter. Ihr Morphic-Credits-Charged-Header ist 0.
• Derselbe Idempotency-Key mit einem anderen Tool oder Body antwortet mit 409 idempotency_conflict.
• Eine Wiederholung, während das Original noch läuft, antwortet mit 409 idempotency_in_progress.
• Eine Wiederholung eines kostenpflichtigen Aufrufs, dessen Original fehlgeschlagen ist (5xx) oder nie geantwortet hat, nachdem es möglicherweise ausgeführt wurde, antwortet mit 409 idempotency_outcome_unknown. Er wird unter demselben Idempotency-Key nie erneut ausgeführt: Prüfen Sie sein Ergebnis und verwenden Sie dann einen neuen Idempotency-Key.
• Idempotency-Keys gelten jeweils für den API-Schlüssel, der sie gesendet hat, und sind bis zu 200 Zeichen lang.

Kostenlose Aufrufe akzeptieren den Header ebenfalls, benötigen ihn aber selten.

Einen kostenpflichtigen Aufruf nach einem 5xx wiederholenCopy Anchor Link

Ein kostenpflichtiger Aufruf, der mit 500, 503 oder 504 antwortet, hat möglicherweise schon Arbeit gestartet und dafür berechnet, bevor er fehlschlug.

1. Prüfen Sie mit list_generations oder mit GET /v1/direct/usage, nach Zeitraum gefiltert, was der Aufruf getan hat.
2. Senden Sie einen neuen Idempotency-Key nur für Arbeit, die nicht gestartet wurde.

Wenn gar keine Antwort eingetroffen ist (eine abgebrochene Verbindung), wiederholen Sie mit demselben Idempotency-Key: Sie erhalten die gespeicherte Antwort oder 409 idempotency_in_progress, solange der Aufruf noch läuft.

Wenn Sie Probleme haben oder Fragen haben, können Sie sich gerne an uns wenden. Wir helfen Ihnen gerne. Schreiben Sie uns an support@morphic.com.