Appeler un outil

Chaque fonctionnalité est un outil, appelé toujours de la même façon : POST /v1/direct/tools/{tool_name}. Le catalogue d’outils les liste tous.

RequêteCopy Anchor Link

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

Un appel complet, avec une clé d’idempotence :

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

RéponseCopy Anchor Link

Chaque succès a la même enveloppe. La sortie propre de l’outil se trouve dans result, telle que la décrit son output_schema.

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

Bloc de facturationCopy Anchor Link

billing est présent dans chaque réponse réussie, appels gratuits compris.

Le bloc indique ce que l’appel a facturé au moment où il a répondu. Les remboursements et les régularisations interviennent plus tard et apparaissent sur la génération, jamais dans la réponse d’origine. Les réponses portent aussi Morphic-Credits-Charged: <integer> pour la journalisation au niveau de votre passerelle. Crédits et consommation explique comment une génération est facturée, régularisée et remboursée.

Refus d’un outilCopy Anchor Link

Lorsque l’entrée est bien formée mais ne peut pas être exécutée (un modèle absent de votre forfait, un format d’image que le modèle ne propose pas, un asset du mauvais type), l’appel répond 422 tool_refused. Le message indique le champ, la valeur et les valeurs qui auraient fonctionné. Rien n’a été lancé et rien n’a été facturé.

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

Lancements partielsCopy Anchor Link

Un appel avec variations supérieur à 1 lance une génération par variation. Si une variation est refusée après que les précédentes ont démarré :

• La réponse reste 202, et result.partial_failure indique ce qui s’est passé.
• result.generation_ids ne liste que ce qui a démarré, et billing ne compte que ce qui a démarré.
• Ne relancez que les variations manquantes.

IdempotenceCopy Anchor Link

Une panne réseau peut survenir après l’envoi d’une requête et avant l’arrivée de sa réponse. Pour réessayer un appel payant sans risque, envoyez un en-tête Idempotency-Key. Utilisez votre propre identifiant de tâche ou de commande.

Idempotency-Key: order-4411-hero-image

• La première requête avec une clé s’exécute normalement.
• Une nouvelle tentative avec la même clé, le même outil et le même corps dans les 24 heures ne s’exécute pas de nouveau. Elle répond 200 avec le corps de la réponse d’origine, y compris les generation_ids et le billing d’origine, et ne facture rien de plus. Son en-tête Morphic-Credits-Charged vaut 0.
• La même clé avec un outil ou un corps différent répond 409 idempotency_conflict.
• Une nouvelle tentative pendant que la requête d’origine est encore en cours répond 409 idempotency_in_progress.
• Une nouvelle tentative d’un appel payant dont l’original a échoué (5xx) ou n’a jamais répondu après avoir pu s’exécuter répond 409 idempotency_outcome_unknown. Il n’est jamais exécuté de nouveau sous la même clé : vérifiez son résultat, puis utilisez une nouvelle clé.
• Les clés sont propres à la clé d’API qui les a envoyées, et comptent jusqu’à 200 caractères.

Les appels gratuits acceptent aussi cet en-tête, mais en ont rarement besoin.

Réessayer un appel payant après une 5xxCopy Anchor Link

Un appel payant qui répond 500, 503 ou 504 peut avoir lancé du travail et l’avoir facturé avant d’échouer.

1. Vérifiez ce que l’appel a fait avec list_generations, ou avec GET /v1/direct/usage filtré par période.
2. N’envoyez un nouvel Idempotency-Key que pour le travail qui n’a pas démarré.

Si aucune réponse n’est arrivée (une connexion coupée), réessayez avec la même clé : vous obtenez la réponse enregistrée, ou 409 idempotency_in_progress tant que l’appel est en cours.

Si vous rencontrez le moindre problème ou si vous avez des questions, n’hésitez pas à nous contacter. Nous serons ravis de vous aider. Écrivez-nous à support@morphic.com.