도구 호출

모든 기능은 하나의 도구이며, 모두 같은 방식으로 호출합니다: POST /v1/direct/tools/{tool_name}. 전체 목록은 도구 카탈로그에 있습니다.

요청Copy Anchor Link

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

멱등성 키를 포함한 전체 호출 예시:

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

응답Copy Anchor Link

모든 성공 응답은 같은 구조를 가집니다. 도구 자체의 출력은 output_schema에 설명된 대로 result에 담깁니다.

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

청구 블록Copy Anchor Link

billing은 무료 호출을 포함한 모든 성공 응답에 포함됩니다.

이 블록은 호출이 반환될 때까지 청구된 금액을 보고합니다. 환불과 정산은 나중에 이루어지며, 원래 응답이 아니라 생성 작업에 표시됩니다. 응답에는 게이트웨이에서 로깅할 수 있도록 Morphic-Credits-Charged: <integer> 헤더도 포함됩니다. 생성 작업이 어떻게 청구, 정산, 환불되는지는 크레딧과 사용량에서 설명합니다.

도구 거부Copy Anchor Link

입력 형식은 올바르지만 실행할 수 없는 경우(플랜에 없는 모델, 모델이 제공하지 않는 화면 비율, 잘못된 유형의 에셋), 호출은 422 tool_refused로 응답합니다. 메시지에는 해당 필드, 값, 그리고 사용할 수 있었던 값이 표시됩니다. 아무것도 시작되지 않았고 아무것도 청구되지 않았습니다.

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

부분 시작Copy Anchor Link

variations가 1보다 큰 호출은 변형마다 생성 작업을 하나씩 시작합니다. 앞의 변형이 시작된 후 뒤의 변형이 거부되면:

• 응답은 여전히 202이며, result.partial_failure에 무슨 일이 있었는지 표시됩니다.
• result.generation_ids에는 시작된 것만 나열되고, billing도 시작된 것만 계산합니다.
• 누락된 변형만 다시 시도하세요.

멱등성Copy Anchor Link

요청이 전송된 후 응답이 도착하기 전에 네트워크 장애가 발생할 수 있습니다. 유료 호출을 안전하게 재시도하려면 Idempotency-Key 헤더를 보내세요. 자체 작업 ID나 주문 ID를 사용합니다.

Idempotency-Key: order-4411-hero-image

• 키를 포함한 첫 요청은 정상적으로 실행됩니다.
• 24시간 안에 같은 키, 도구, 본문으로 재시도하면 다시 실행되지 않습니다. 원래의 generation_ids와 billing을 포함한 원래 응답 본문과 함께 200으로 응답하며, 추가로 청구하지 않습니다. 이때 Morphic-Credits-Charged 헤더는 0입니다.
• 같은 키를 다른 도구나 본문과 함께 보내면 409 idempotency_conflict로 응답합니다.
• 원래 요청이 아직 실행 중일 때 재시도하면 409 idempotency_in_progress로 응답합니다.
• 원래 요청이 실패했거나(5xx) 실행되었을 수 있는 시점 이후 응답하지 않은 유료 호출을 재시도하면 409 idempotency_outcome_unknown으로 응답합니다. 같은 키로는 절대 다시 실행되지 않으므로, 결과를 확인한 다음 새 키를 사용하세요.
• 멱등성 키는 그 키를 보낸 API 키별로 구분되며, 최대 200자입니다.

무료 호출도 이 헤더를 받지만 필요한 경우는 드뭅니다.

5xx 이후 유료 호출 재시도Copy Anchor Link

500, 503 또는 504로 응답한 유료 호출은 실패하기 전에 작업을 시작하고 비용을 청구했을 수 있습니다.

1. list_generations나 시간으로 필터링한 GET /v1/direct/usage로 호출이 무엇을 했는지 확인합니다.
2. 시작되지 않은 작업에 대해서만 새 Idempotency-Key를 보냅니다.

응답이 전혀 도착하지 않은 경우(연결 끊김)에는 같은 키로 재시도하세요. 저장된 응답을 받거나, 아직 실행 중이면 409 idempotency_in_progress를 받습니다.

문제가 있거나 궁금한 점이 있으면 언제든지 연락해 주세요. 기꺼이 도와드리겠습니다. 다음 주소로 이메일을 보내 주세요: support@morphic.com.