Chamar uma ferramenta

Cada funcionalidade é uma ferramenta, chamada sempre da mesma forma: POST /v1/direct/tools/{tool_name}. O catálogo de ferramentas lista todas elas.

SolicitaçãoCopy Anchor Link

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

Uma chamada completa, com uma chave de idempotência:

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

RespostaCopy Anchor Link

Todo sucesso tem o mesmo envelope. A saída da própria ferramenta fica em result, conforme descrito no seu 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"]
  }
}

Bloco de cobrançaCopy Anchor Link

billing está presente em toda resposta de sucesso, inclusive nas chamadas gratuitas.

O bloco informa o que a chamada cobrou no momento em que respondeu. Reembolsos e acertos acontecem depois e aparecem na geração, nunca na resposta original. As respostas também trazem Morphic-Credits-Charged: <integer> para registro no seu gateway. Créditos e uso explica como uma geração é cobrada, acertada e reembolsada.

Recusas da ferramentaCopy Anchor Link

Quando a entrada está bem formada mas não pode ser executada (um modelo que o seu plano não inclui, uma proporção que o modelo não oferece, um recurso do tipo errado), a chamada responde 422 tool_refused. A mensagem indica o campo, o valor e os valores que funcionariam. Nada foi iniciado e nada foi cobrado.

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

Inícios parciaisCopy Anchor Link

Uma chamada com variations acima de 1 inicia uma geração por variação. Se uma variação posterior for recusada depois que as anteriores já começaram:

• A resposta continua sendo 202, e result.partial_failure informa o que aconteceu.
• result.generation_ids lista apenas o que foi iniciado, e billing conta apenas o que foi iniciado.
• Tente de novo apenas as variações que faltaram.

IdempotênciaCopy Anchor Link

Uma falha de rede pode ocorrer depois que a solicitação foi enviada e antes de a resposta chegar. Para repetir uma chamada paga com segurança, envie um cabeçalho Idempotency-Key. Use o ID do seu próprio job ou pedido.

Idempotency-Key: order-4411-hero-image

• A primeira solicitação com uma chave é executada normalmente.
• Uma nova tentativa com a mesma chave, a mesma ferramenta e o mesmo corpo dentro de 24 horas não é executada de novo. Ela responde 200 com o corpo da resposta original, incluindo os generation_ids e o billing originais, e não cobra nada a mais. O cabeçalho Morphic-Credits-Charged dela é 0.
• A mesma chave com outra ferramenta ou outro corpo responde 409 idempotency_conflict.
• Uma nova tentativa enquanto a original ainda está em execução responde 409 idempotency_in_progress.
• Uma nova tentativa de uma chamada paga cuja original falhou (5xx) ou nunca respondeu depois de possivelmente ter sido executada responde 409 idempotency_outcome_unknown. Ela nunca é executada de novo com a mesma chave: verifique o resultado e depois use uma chave nova.
• As chaves valem apenas para a chave de API que as enviou e têm até 200 caracteres.

Chamadas gratuitas também aceitam o cabeçalho, mas raramente precisam dele.

Repetir uma chamada paga após um 5xxCopy Anchor Link

Uma chamada paga que responde 500, 503 ou 504 pode ter iniciado trabalho e cobrado por ele antes de falhar.

1. Verifique o que a chamada fez com list_generations ou com GET /v1/direct/usage filtrado por horário.
2. Envie um novo Idempotency-Key apenas para o trabalho que não foi iniciado.

Quando nenhuma resposta chegou (uma conexão interrompida), tente de novo com a mesma chave: você recebe a resposta armazenada, ou 409 idempotency_in_progress enquanto ela ainda estiver em execução.

Se você tiver algum problema ou alguma dúvida, entre em contato. Teremos prazer em ajudar. Escreva para nós em support@morphic.com.