Direct API
자체 백엔드에서 HTTPS로 Morphic의 이미지, 동영상, 오디오를 생성하고 편집하고 관리합니다.
Morphic Direct API는 Morphic MCP 서버가 AI 어시스턴트에 제공하는 것과 같은 생성, 편집, 라이브러리 도구를 일반 HTTPS와 JSON으로 백엔드에 제공합니다. 조직 API 키로 도구를 호출하고, 모든 유료 호출은 청구된 금액을 알려 주며, 각 생성 작업은 폴링이나 서명된 웹훅으로 추적합니다.
한눈에 보기
| 기본 URL | https://mcp.morphic.com/v1/direct |
|---|---|
| 인증 | Authorization: Bearer mor_live_… |
| 형식 | JSON 요청 및 응답 본문, UTF-8, 요청당 최대 1 MB |
| ID | 데이터에는 UUID v7 문자열, 모델에는 mdl_…, 음성에는 list_voices가 반환하는 UUID |
| 시간 | UTC 기준 ISO 8601, 예: 2026-10-25T09:14:03.120Z |
| 금액 | 정수로 표시되는 Morphic 크레딧: 플랜과 Studio에서 사용하는 것과 같은 크레딧 |
액세스 받기
Direct API는 초대를 통해 조직별로 활성화됩니다. 활성화되기 전에는 모든 호출이 403 direct_api_disabled로 응답합니다.
- Morphic 담당자에게 조직의 Direct API 활성화를 요청하세요. 주문서가 준비되면 Morphic이 유료 도구도 활성화합니다. 그 전에는 Studio에 Direct API 범위가 표시되지 않으며, 유료 도구는
403 tool_not_available로 응답합니다. - 조직 관리자가 Studio의 '설정' > 'API 키'에서 키를 만들고, 조직을 대표하여 개발자 API 섹션을 포함한 Morphic 이용약관에 동의합니다. 키 만들기를 참조하세요.
Authorization: Bearer <secret>헤더로 API를 호출합니다.
빠른 시작
결과물을 저장할 프로젝트를 찾고, 이미지 생성을 시작한 다음, 완료될 때까지 기다립니다.
export MORPHIC_API_KEY=mor_live_9f2c… # created once in Studio > Settings > API keys
# 1. Which project should the output land in?
curl -s https://mcp.morphic.com/v1/direct/tools/list_projects \
-H "Authorization: Bearer $MORPHIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {}}'
# 2. Start an image
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, soft morning light",
"aspect_ratio": "16:9",
"project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f"
},
"webhook_id": "01929a10-0c3d-7f44-8a21-0b1c2d3e4f50",
"metadata": { "order_id": "4411" }
}'
# 3. Wait for it (holds up to 45 s, returns the moment it finishes)
curl -s "https://mcp.morphic.com/v1/direct/generations/0192a7b3-…?wait=45" \
-H "Authorization: Bearer $MORPHIC_API_KEY"모든 생성 결과는 Studio에서 만든 것과 똑같이 조직의 Morphic 라이브러리 안, 지정한 프로젝트에 저장됩니다. Studio에서는 API로 생성된 것으로 표시되며, 라이브러리의 '생성자' > 'API' 필터를 사용하면 API 키로 만들거나 가져온 모든 항목을 볼 수 있습니다.
엔드포인트
| 메서드 | 경로 | 범위 | 기능 |
|---|---|---|---|
GET | /v1/direct/me | 없음 | 키, 키의 한도와 사용량, 조직의 잔액 |
GET | /v1/direct/tools | 없음 | JSON Schema가 포함된 도구 카탈로그 |
GET | /v1/direct/tools/{tool_name} | 없음 | 도구 하나 |
GET | /v1/direct/openapi.json | 없음 | OpenAPI 3.1 문서 |
POST | /v1/direct/tools/{tool_name} | 도구별 | 도구 호출 |
GET | /v1/direct/generations/{id} | assets:read | 생성 작업 하나, 선택적 롱 폴링 |
POST | /v1/direct/generations/batch-get | assets:read | 생성 작업 최대 10개, 선택적 롱 폴링 |
GET | /v1/direct/usage | assets:read | 원장 항목과 합계 |
POST | /v1/direct/webhooks | generations:write | 엔드포인트 등록 |
GET | /v1/direct/webhooks | assets:read | 엔드포인트 목록 |
DELETE | /v1/direct/webhooks/{webhook_id} | generations:write | 엔드포인트 삭제 |
GET | /v1/direct/webhooks/{webhook_id}/events | assets:read | 전달 로그 |
다음 읽을거리
인증
키, 범위, 크레딧 한도
도구 호출
요청, 응답, 청구, 멱등성
생성 작업
상태, 폴링, 일괄 조회
웹훅
생성 작업이 끝나면 받는 서명된 알림
크레딧과 사용량
각 호출의 청구 금액, /me와 /usage
자체 미디어 전달하기
모든 미디어 필드에 URL로 파일 전달
오류
모든 오류 코드와 재시도 시점
한도
요청 속도 한도와 크기 한도
도구 카탈로그
모든 도구와 필요한 범위
모델
모델 ID, 기능, 옵션
버전 관리
v1 안에서 바뀔 수 있는 것
문제가 있거나 궁금한 점이 있으면 언제든지 연락해 주세요. 기꺼이 도와드리겠습니다. 다음 주소로 이메일을 보내 주세요: support@morphic.com.