크레딧과 사용량

Direct API는 Studio와 같은 크레딧 풀인 조직의 잔액에서 Morphic 크레딧을 차감하며, 모든 응답에 차감한 크레딧 수가 표시됩니다.

• Direct API 호출은 조직의 API 요율로 청구되며, 이는 Studio에서 같은 작업에 드는 비용과 다를 수 있습니다. API가 제공하는 모든 수치에는 이미 이 요율이 반영되어 있습니다: plan_media 견적, estimated_credits, billing 블록, 생성 작업 조회, 웹훅, /usage.
• 요율은 조직별로 정해지며 공개되지 않습니다. 계정 담당자가 API 요율표를 공유해 드릴 수 있습니다.
• 요율 변경은 변경 이후 시작된 생성 작업에 적용됩니다. 진행 중인 생성 작업은 시작 당시의 요율로 정산됩니다.
• Studio의 '설정' > '크레딧'에서 API 사용량은 멤버 옆에 'API'라는 별도의 행으로 표시되며, 'API를 키별로 보기'로 키별 내역을 볼 수 있습니다. API 사용량은 조직의 크레딧에서 차감되지만 멤버의 할당량에서는 절대 차감되지 않으며, 각 키의 크레딧 한도로 상한이 정해집니다.

생성 작업이 청구되는 방식Copy Anchor Link

1. 시작할 때 생성 작업에 견적 가격이 청구됩니다. 시작 응답은 이를 billing.credits_charged와 result.estimated_credits에 표시합니다.
2. 일부 출력은 실제로 생성된 양에 따라 가격이 정해집니다. 음성과 음악은 생성된 길이로, 타임라인 렌더링은 연산 시간으로 정해집니다. 이런 출력에는 credits_settle_on_output_duration: true가 표시되며, 시작 시 청구액은 최저 금액이고 최종 금액은 생성 작업이 끝날 때 정산됩니다.
3. failed나 cancelled로 끝난 생성 작업은 전액 환불되며, 돌려준 크레딧은 billing.credits_refunded에 표시됩니다. 성공한 생성 작업도 부분 환불을 받을 수 있습니다. 예를 들어 정산 대상 출력이 시작 시 청구액에 해당하는 길이보다 짧게 나온 경우입니다.
4. 생성 작업이 최종 상태가 되면 billing.credits_charged는 원장의 순 합계(시작 시 청구액에 정산액을 더하거나 뺀 뒤 credits_refunded를 뺀 값)가 되고, credits_are_final은 true가 됩니다. 실패하거나 취소된 생성 작업은 credits_charged: 0으로 끝나며, credits_refunded는 청구되었던 금액과 같습니다.

생성 작업이 실행되는 동안 credits_charged는 시작 시 청구액과 같습니다. 정산된 금액은 생성 작업이 최종 상태가 된 후 다시 조회하세요. 웹훅은 최종 상태가 된 후에만 전송됩니다.

응답별 청구 내역Copy Anchor Link

호출 응답의 billing 블록은 호출이 반환될 때까지 청구된 금액을 보고합니다. 호출 종류별 내용은 도구 호출에 나와 있습니다. 환불은 나중에 이루어지므로, 원래 응답이 아니라 생성 작업(GET /generations/{id}와 /usage)에 표시됩니다.

• analyze_video처럼 호출 안에서 응답하는 유료 도구의 작업이 실패하면, credits_charged: 0과 환불액이 설정된 credits_refunded로 응답합니다.
• Morphic-Credits-Charged: <integer> 헤더는 billing.credits_charged와 같은 숫자를 담습니다. 단, 멱등 재실행은 추가로 청구하지 않으므로 헤더는 0을 보내고 본문은 원래 청구액을 그대로 반복합니다.

사용 전에 견적 받기Copy Anchor Link

POST /v1/direct/tools/plan_media는 최대 20단계로 된 계획을 검증하고, 가능한 단계의 가격을 매기며, 아무것도 시작하거나 청구하지 않습니다.

curl -s https://mcp.morphic.com/v1/direct/tools/plan_media \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input": {
          "steps": [
            { "id": "still", "tool_name": "generate_image", "arguments_json": "{\"prompt\":\"A red vintage bicycle\",\"aspect_ratio\":\"16:9\"}" },
            { "id": "clip", "tool_name": "generate_video", "arguments_json": "{\"prompt\":\"The bicycle rolls away\",\"duration_seconds\":8}", "depends_on": ["still"] }
          ]
        }
      }'

• 아직 출력이 없는 에셋 필드는 비워 두고, 그 출력을 만드는 단계를 depends_on에 지정하세요.
• 각 단계에는 validation, quote_status, estimated_credits가 주어집니다.
• 결과에는 execution_order, known_estimated_credits, unquoted_step_ids, complete_estimate도 포함됩니다. complete_estimate가 false이면 합계는 예산이 아니라 하한값입니다.

키와 잔액Copy Anchor Link

GET /v1/direct/me는 호출한 키, 키의 한도와 사용량, 조직의 잔액을 반환합니다. 모든 키가 호출할 수 있습니다.

curl -s https://mcp.morphic.com/v1/direct/me \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "api_key": {
    "id": "01928e00-…",
    "name": "Order pipeline (prod)",
    "scopes": ["assets:read", "assets:write", "generations:write", "projects:read"],
    "expires_at": null,
    "credit_limits": {
      "total":   { "limit": 500000, "used": 182340, "remaining": 317660 },
      "monthly": { "limit": 100000, "used": 41200,  "remaining": 58800, "resets_at": "2026-11-01T00:00:00.000Z" },
      "daily":   { "limit": null,   "used": 2310,   "remaining": null,  "resets_at": "2026-10-26T00:00:00.000Z" }
    }
  },
  "organization": {
    "id": "01928d00-…",
    "plan": "enterprise",
    "remaining_credits": 1240000,
    "unlimited": false
  }
}

사용량 원장Copy Anchor Link

GET /v1/direct/usage(범위 assets:read)는 자체 기록과 대조할 수 있도록 키로 인해 발생한 모든 원장 항목을 반환합니다.

curl -s "https://mcp.morphic.com/v1/direct/usage?from=2026-10-01T00:00:00Z&limit=200" \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "usage": [
    { "id": "0192a7b3-…", "created_at": "2026-10-25T09:14:03.500Z", "kind": "charge",     "credits": 120, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } },
    { "id": "0192a7b4-…", "created_at": "2026-10-25T09:15:41.950Z", "kind": "settlement", "credits": -24, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } }
  ],
  "totals": { "charged": 120, "settled": -24, "refunded": 0, "net": 96 },
  "next_cursor": null
}

• kind는 charge, settlement, refund 중 하나이며, credits가 음수이면 크레딧을 돌려준 것입니다.
• totals는 페이지만이 아니라 필터링된 전체 범위를 대상으로 합니다.
• 호출 안에서 응답하는 도구(analyze_video, analyze_audio, filmlab_edit)는 생성 작업을 시작하지 않으므로, 그 항목에는 generation_id: null이 표시되며 tool로 구분합니다.

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