Llamar a una herramienta

Cada capacidad es una herramienta, y todas se llaman igual: POST /v1/direct/tools/{tool_name}. El catálogo de herramientas las enumera todas.

SolicitudCopy Anchor Link

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

Una llamada completa, con clave de idempotencia:

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

RespuestaCopy Anchor Link

Toda respuesta correcta tiene el mismo sobre. La salida propia de la herramienta está en result, tal como la describe su 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"]
  }
}

Bloque de facturaciónCopy Anchor Link

billing está presente en todas las respuestas correctas, incluidas las de llamadas gratuitas.

El bloque informa de lo que cobró la llamada en el momento de responder. Los reembolsos y las liquidaciones se producen después y aparecen en la generación, nunca en la respuesta original. Las respuestas también llevan Morphic-Credits-Charged: <integer> para registrarlo en su gateway. Créditos y uso explica cómo se cobra, se liquida y se reembolsa una generación.

Rechazos de herramientasCopy Anchor Link

Cuando la entrada está bien formada pero no puede ejecutarse (un modelo que su plan no incluye, una relación de aspecto que el modelo no ofrece, un recurso del tipo equivocado), la llamada responde 422 tool_refused. El mensaje indica el campo, el valor y los valores que habrían funcionado. No se inició nada y no se cobró nada.

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

Inicios parcialesCopy Anchor Link

Una llamada con variations mayor que 1 inicia una generación por variación. Si una variación posterior se rechaza después de que se iniciaran las anteriores:

• La respuesta sigue siendo 202, y result.partial_failure indica lo que ocurrió.
• result.generation_ids solo enumera lo que se inició, y billing solo cuenta lo que se inició.
• Reintente solo las variaciones que faltan.

IdempotenciaCopy Anchor Link

Un fallo de red puede producirse después de enviar una solicitud y antes de que llegue su respuesta. Para reintentar una llamada de pago con seguridad, envíe un encabezado Idempotency-Key. Use su propio id de trabajo o de pedido.

Idempotency-Key: order-4411-hero-image

• La primera solicitud con una clave se ejecuta con normalidad.
• Un reintento con la misma clave, la misma herramienta y el mismo cuerpo en un plazo de 24 horas no se vuelve a ejecutar. Responde 200 con el cuerpo de la respuesta original, incluidos los generation_ids y el billing originales, y no cobra nada más. Su encabezado Morphic-Credits-Charged es 0.
• La misma clave con otra herramienta u otro cuerpo responde 409 idempotency_conflict.
• Un reintento mientras la solicitud original sigue en curso responde 409 idempotency_in_progress.
• Un reintento de una llamada de pago cuya solicitud original falló (5xx) o nunca respondió después de haberse podido ejecutar responde 409 idempotency_outcome_unknown. Nunca se vuelve a ejecutar con la misma clave: compruebe su resultado y luego use una clave nueva.
• Las claves se asocian a la clave de API que las envió y admiten hasta 200 caracteres.

Las llamadas gratuitas también aceptan el encabezado, aunque rara vez lo necesitan.

Reintentar una llamada de pago después de un 5xxCopy Anchor Link

Una llamada de pago que responde 500, 503 o 504 puede haber iniciado trabajo y haberlo cobrado antes de fallar.

1. Compruebe lo que hizo la llamada con list_generations, o con GET /v1/direct/usage filtrado por fecha y hora.
2. Envíe un Idempotency-Key nuevo solo para el trabajo que no se inició.

Cuando no llegó ninguna respuesta (una conexión interrumpida), reintente con la misma clave: obtendrá la respuesta guardada, o 409 idempotency_in_progress mientras siga en curso.

Si tiene algún problema o alguna pregunta, no dude en ponerse en contacto con nosotros. Estaremos encantados de ayudarle. Escríbanos a support@morphic.com.