생성 작업
롱 폴링으로 Direct API 생성 작업을 최종 상태까지 추적하고, 여러 작업을 한 번에 조회하며, 폴링 시점을 알아봅니다.
생성 작업은 비동기 작업의 한 단위입니다: 이미지 하나, 동영상 하나, 오디오 트랙 하나, 렌더링 하나. returns_generation: true인 도구는 생성 작업을 하나 이상 시작하고 그 ID와 함께 즉시 응답합니다. 생성 작업은 폴링, 웹훅 또는 둘 다로 추적합니다. 웹훅을 주요 신호로 사용하고, 가끔 하는 폴링을 안전장치로 두세요.
상태
queued ──► in_progress ──► succeeded
│ │
│ ├──────► failed
└─────────────┴──────► cancelled| 상태 | 최종 | 의미 |
|---|---|---|
queued | 아니요 | 접수됨, 모델 처리 용량을 기다리는 중 |
in_progress | 아니요 | 모델이 작업 중 |
succeeded | 예 | assets에 출력이 담겨 있음 |
failed | 예 | error에 이유가 표시됨. 청구 금액은 환불되며 billing.credits_refunded에 환불액이 표시됨 |
cancelled | 예 | 출력을 만들기 전에 중단됨. 청구 금액은 환불됨 |
알 수 없는 상태는 최종 상태가 아닌 것으로 간주하고 생성 작업을 계속 추적하세요. 새로운 중간 상태가 추가될 수 있습니다.
생성 작업 객체
{
"object": "generation",
"id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
"tool": "generate_video",
"status": "succeeded",
"project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
"model_id": "mdl_7rk2pq9vxa4m",
"created_at": "2026-10-25T09:14:03.120Z",
"completed_at": "2026-10-25T09:15:41.902Z",
"error": null,
"billing": {
"estimated_credits": 120,
"credits_charged": 96,
"credits_refunded": 0,
"credits_are_final": true,
"credits_settle_on_output_duration": true
},
"assets": [
{
"id": "0192a7b4-0f1e-7d3c-9b8a-7c6d5e4f3a2b",
"type": "video",
"name": "Bicycle hero shot",
"mime_type": "video/mp4",
"width": 1920,
"height": 1080,
"duration_seconds": 8,
"url": "https://mcp.morphic.com/m/Xk29dPq",
"url_expires_at": null,
"studio_url": "https://studio.morphic.com/…",
"final_generation_expires_at": null
}
],
"content_left_out": [],
"render_warnings": [],
"metadata": { "order_id": "4411" },
"poll_after_seconds": null
}| 필드 | 의미 |
|---|---|
error | null, 또는 failed일 때 { "error_code": "…", "message": "…" }. 메시지는 사용자에게 그대로 보여 줘도 안전합니다. |
billing | 이 생성 작업의 비용. 크레딧과 사용량 참조 |
assets[].id | 다른 도구가 입력으로 받는 에셋 ID(image_asset_id, video_asset_id, …) |
assets[].url | 미디어를 다운로드하는 짧은 링크. 만료되지 않으며 url_expires_at은 null |
assets[].studio_url | 팀이 Morphic Studio에서 에셋을 열 수 있는 링크 |
assets[].final_generation_expires_at | 초안 동영상 전용: finalize_video_draft로 전체 해상도 렌더링이 가능한 기한 |
content_left_out, render_warnings | 합성과 타임라인 내보내기 전용: 출력에 포함하지 못한 내용과 그 이유 |
poll_after_seconds | 최종 상태가 아닐 때 다음 조회까지 기다릴 시간. 최종 상태가 되면 null |
생성 작업 하나 조회
GET /v1/direct/generations/{id}는 { "generation": { … } }와 함께 200으로 응답합니다.
curl -s "https://mcp.morphic.com/v1/direct/generations/$ID?wait=45" \
-H "Authorization: Bearer $MORPHIC_API_KEY"wait는 선택 사항이며0에서45초 사이입니다. 생성 작업의 상태가 바뀌거나 작업이 끝날 때까지 요청이 열린 채로 유지되고, 그 즉시 응답합니다.- 대기 시간이 다 지나면 현재 상태로 응답합니다. 45보다 큰 값은 45로 제한됩니다.
- 다른 조직의 생성 작업이나 이 키로 읽을 수 없는 생성 작업은
403이 아니라404로 응답하므로, ID를 탐색할 수 없습니다.
생성 작업 여러 개 조회
POST /v1/direct/generations/batch-get은 한 번의 요청으로 생성 작업을 최대 10개까지 조회합니다.
curl -s https://mcp.morphic.com/v1/direct/generations/batch-get \
-H "Authorization: Bearer $MORPHIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids": ["0192a7b3-…", "0192a7b3-…"], "wait": 30}'wait를 지정하면 그중 하나라도 상태가 바뀌거나 모두 최종 상태가 되는 즉시 응답합니다.- 응답은 요청한 순서대로
{ "generations": [ … ], "not_found": ["…"] }입니다.
폴링 빈도
모든 시작 응답과 최종 상태가 아닌 조회 응답에는 poll_after_seconds가 포함됩니다. 다음 조회까지 최소한 그 시간만큼 기다린 다음, 간격을 점점 늘리세요.
| 출력 | 첫 폴링 시점 | 최종 상태까지 일반적인 시간 |
|---|---|---|
| 이미지, 이미지 편집, 업스케일, 이미지 작업 | 5초 | 5~60초 |
| 음성, 효과음, 전사 | 10초 | 10~90초 |
| 음악, 대화 | 20초 | 30초~3분 |
| 동영상, 동영상 편집, 립싱크, 렌더링 | 30초 | 1~10분, 부하가 많으면 더 길어짐 |
롱 폴링(wait=45)은 아무리 오래 유지되어도 조회 한 번으로 계산되므로, 가장 빠르면서 가장 저렴한 폴링 방법입니다. HTTP 클라이언트의 타임아웃은 대기 시간보다 길게 설정하세요. wait=45라면 60초입니다.
import time, requests
def wait_for(generation_id, key):
headers = {"Authorization": f"Bearer {key}"}
url = f"https://mcp.morphic.com/v1/direct/generations/{generation_id}"
while True:
r = requests.get(url, params={"wait": 45}, headers=headers, timeout=60)
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
gen = r.json()["generation"]
if gen["status"] in ("succeeded", "failed", "cancelled"):
return gen
# A long-poll already waited; only sleep if the server asks for more.
time.sleep(max(0, (gen.get("poll_after_seconds") or 0) - 45))폴링 한도
| 한도 | 값 | 초과 시 |
|---|---|---|
| 키 하나가 생성 작업 하나를 조회하는 횟수 | 분당 30회 | 429, Retry-After |
| 키 하나가 모든 생성 작업을 조회하는 횟수 | 분당 1,200회 | 429, Retry-After |
wait | 45초 | 제한됨 |
| 일괄 조회당 ID 수 | 10 | 400 |
일괄 조회는 두 한도 모두에 대해 ID마다 한 번씩 계산됩니다. 권장 주기로 폴링하면 키 하나로 진행 중인 생성 작업 수백 개를 동시에 추적할 수 있습니다. 그보다 많이 추적한다면 웹훅을 사용하세요.
문제가 있거나 궁금한 점이 있으면 언제든지 연락해 주세요. 기꺼이 도와드리겠습니다. 다음 주소로 이메일을 보내 주세요: support@morphic.com.