# 3D 장면

> 프롬프트로 편집 가능한 3D 클레이 장면을 만들고, 수정하고, MP4로 렌더링한 뒤, 그 렌더링을 동영상 모델의 레이아웃과 움직임 가이드로 사용하세요.

Source: https://nodaro.ai/ko/docs/mcp/3d-scenes

**3D 장면**은 편집 가능한 애니메이션 클레이 장면입니다. 단순한 도형과 키프레임 움직임으로 이루어지며, 프롬프트와 선택적인 이미지나 동영상 레퍼런스로 작성합니다. AI 어시스턴트에서 장면을 만들고, 말로 하는 지시나 정확한 연산으로 수정하고, MP4로 렌더링한 뒤, 그 렌더링을 동영상 모델의 레이아웃과 움직임 가이드로 사용합니다. MCP 도구는 캔버스의 [**3D 장면 생성**](https://nodaro.ai/docs/nodes/video/generate-3d-scene) 노드와 [**3D 장면 편집**](https://nodaro.ai/docs/nodes/video/edit-3d-scene) 노드와 같은 일을 합니다.

## 도구
| 도구 | 하는 일 |
| --- | --- |
| `generate_3d_scene` | 프롬프트와 선택적인 레퍼런스로 편집 가능한 장면을 만듭니다 |
| `edit_3d_scene` | 장면 리비전과 지시 또는 연산으로 새 리비전을 만듭니다 |
| `render_3d_scene` | 지정한 장면 리비전을 **동영상 렌더링** 엔진으로 MP4로 만듭니다 |
| `pro_3d_render` | 장면 작성, 수정, 내보내기 중 하나를 작업 하나로 처리하고, 장면 플랜, MP4, 샷마다 스틸 이미지 한 장을 반환합니다. 이 엔진이 있는 배포 환경에서만 사용할 수 있습니다 |

각 도구에는 `workflows:execute`가 필요하며, 도구는 작업 ID를 반환합니다. 결과는 `get_job` 또는 `wait_for_job`으로 읽으세요. 장면 작업은 `output_data.scenePlan`을 반환하고, 렌더링은 동영상 URL을 반환합니다. 파라미터는 [도구 레퍼런스](https://nodaro.ai/docs/mcp/tools/3d-scenes)에 있습니다.

## 기본 흐름
### 장면 생성
샷 설명, `duration_seconds`, `fps`, `aspect_ratio`를 넣어 `generate_3d_scene`을 호출하세요. 레퍼런스는 `{ id, url, kind, role }` 형식이며, 외형, 레이아웃 또는 움직임에 쓰는 이미지나 동영상입니다.

### 수정
완료된 작업에서 `scenePlan`을 읽으세요. 그 객체를 `scene_plan`으로, 그 `revisionId`를 `expected_revision_id`로 넣고, 편집 `prompt`나 `operations` 중 하나를 붙여 `edit_3d_scene`을 호출하세요. 바뀌면 안 되는 객체는 `locked_object_ids`에 나열하세요.

### 렌더링
결과로 나온 `scene_plan`으로 `render_3d_scene`을 호출하세요. LLM은 실행되지 않습니다.

### 렌더링을 가이드로 사용
MP4를 `reference_video_urls`에 넣어 [`generate_video`](https://nodaro.ai/docs/mcp/tools/video#generate_video)에 전달하고, 같은 위치의 `reference_video_captions`에 그 용도를 적으세요. 외형 이미지도 계속 레퍼런스로 전달하세요.

클레이 렌더링은 레이아웃 가이드이지, 따라 할 외형이 아닙니다. 캡션이 없으면 동영상 모델이 회색 클레이 외형까지 따라 할 수 있습니다.

## 첫 버전에서 할 수 있는 것
- **도형과 움직임.** 장면은 기본 도형과 결정론적인 키프레임 애니메이션을 사용합니다.
- **레퍼런스는 근사치입니다.** 레퍼런스로 다시 만든 장면은 그 레퍼런스의 근사치입니다.
- **동영상 레퍼런스는 전체를 사용합니다.** 동영상 레퍼런스는 통째로 사용됩니다. 일부 구간만 쓰려면 먼저 클립을 트리밍하고 트리밍한 URL을 전달하세요. 일부 시간 구간을 지정하면 작성 비용이 청구되기 전에 거부됩니다.
- **연산에는 LLM 호출이 없습니다.** `operations`로 하는 편집은 바로 적용됩니다. 렌더링도 마찬가지입니다.

## 엔진
`generate_3d_scene`과 `edit_3d_scene`은 `engine`을 받습니다. 값은 `basic`(기본값), `blender-cloud`, `blender-local` 중 하나입니다. 고급 엔진은 배포 환경에서 사용할 수 있어야 하며, 사용할 수 없는 엔진은 거부되고 절대 `basic`으로 대체되지 않습니다. 고급 엔진은 고정된 플래너를 사용하므로 `llm_model`과 `reasoning_effort`는 빼고, 보정 한도는 `max_repair_passes`로 설정하세요.

가져오기를 지원하는 고급 엔진에서는 `generate_3d_scene`이 `input_assets`도 받습니다. 기존 3D 모델(GLB)을 최대 8개까지 지정할 수 있으며, 각각 `{ id, revisionId, assetId, label }` 형식입니다. 이미지와 동영상은 계속 `references`에 넣으세요. 엔진이 가져오기를 지원하지 않으면 가져오기는 비용이 청구되기 전에 거부됩니다. 서버가 파일을 직접 찾으므로 URL이나 해시는 절대 보내지 마세요.

## 렌더링 비용
렌더링 가격은 전달한 플랜의 프레임 크기로 정해집니다.

| 프레임 | 크레딧 |
| --- | --- |
| 가장 긴 변이 1920픽셀 이하 | 55 |
| 그보다 크고 5.12메가픽셀 이하 | 83 |
| 그보다 큼 | 138 |

장면 플랜의 `width`와 `height`는 의도해서 설정하세요. 2560×2560 장면은 1920×1080 장면의 2.5배 비용이 들지만, 1920×1920은 1920×1080과 비용이 같습니다. 전체 표는 [**동영상 렌더링**](https://nodaro.ai/docs/nodes/video/render-video)에 있습니다.

## 고급 엔진의 결과 읽기
고급 엔진이 작성한 장면은 엔진이 가정한 것과 실행한 것을 보고합니다. 다음 필드는 모두 선택 사항이며, `basic` 엔진은 이 중 어느 것도 보고하지 않습니다.

| 필드 | 보고하는 내용 |
| --- | --- |
| `SCENE_AUTHORING_ASSUMPTION`이 있는 `validation.warnings[]` | 플래너의 가정 |
| `metadata.summary` | 작성한 것에 대한 엔진 자체의 설명 |
| `repairPasses` | 실행된 수정. 장면이 처음에 바로 받아들여졌으면 `0` |
| `admissionRetries` | 빌드 전 플래너의 재시도. 수정 패스를 소모하지 않습니다 |
| `mechanicalPasses` | 플래너 호출 없이 컴파일러 자체의 수정안으로 엔진이 적용한 수정이며, 각각 `REMEDY_AUTO_APPLIED` 경고가 붙습니다. `repairPasses`와 따로, 견적에 포함된 별도 한도로 셉니다. |
| `restoredAssertions` | 응답이 바꾼 필수 검사를 엔진이 되돌린 것이며, 각각 `ASSERTION_RESTORED` 경고가 붙습니다 |

렌더링 전용 내보내기는 아무것도 작성하지 않으므로, 요약을 보고하지 않고 횟수도 생략합니다.

### 완료된 장면이 승인되지 않았을 때
완료된 작업에 `metadata.review`가 있을 수 있습니다. 이는 시각적 검토의 승인 없이 장면이 전달되었다는 뜻입니다. 상태나 경고 수가 아니라 `metadata.review`가 있는지를 확인하고, 사용자에게 무엇이든 알리기 전에 그 `verdict`를 읽으세요.

- **`refused`**: 수정 한도를 다 썼고 모든 필수 검사를 통과했지만, 검토가 여전히 이의를 제기했습니다. 장면에는 이의 내용과, 이의 하나당 `SCENE_REVIEW_REFUSED` 경고 하나가 함께 옵니다.
- **`unavailable`**: 검토가 `attempts`번 시도하는 동안 쓸 수 있는 판정을 내지 못했습니다. `reason`은 검토가 모델에 닿지 못했으면 `provider`, 응답을 쓸 수 없었으면 `unusable`입니다. 아무도 장면을 판단하지 않았으며, `validation.warnings[]`는 `SCENE_REVIEW_UNAVAILABLE`로 시작합니다. 아무도 검토하지 않은 장면을 거부되었다고 보고하지 마세요.

두 경우 모두 `validation.status`는 여전히 `passed`이며, 이의 목록이 비어 있을 수도 있습니다.

### 고급 작업이 실패했을 때
`SCENE_QUALITY_FAILED`로 실패한 작업은 자신 있게 내놓을 장면 없이 한도를 다 쓴 것입니다. 다시 실행하기 전에 그 작업의 `output_data`를 읽으세요.

- **초안이 만들어진 경우.** 실패한 작업은 `scenePlan`, `sceneRevisionId`, `deliveryId`, `posterAssetId`로 초안을 가리키며, `validation.status`는 `failed`입니다. 초안은 일반 리비전이므로 `edit_3d_scene`이나 `render_3d_scene`에 전달하세요.
- **아무것도 컴파일되지 않은 경우.** `scenePlan`은 없지만 작업에는 여전히 `deliveryId`가 있고, `validation.sourceRetained`가 레시피가 보관되었는지 알려 줍니다. REST API에서 `GET /v1/3d-scene/deliveries/{deliveryId}`로 가져온 다음, 그 `source-json` 에셋을 가져오세요. 읽는 데 크레딧은 들지 않지만, 내 자격 증명과 작업 워크플로의 편집 권한이 필요합니다. 이를 위한 MCP 도구는 없습니다.

똑같은 프롬프트를 다시 실행하면 같은 작성 비용을 두 번 냅니다.

## 3D 렌더링 Pro
[`pro_3d_render`](https://nodaro.ai/docs/mcp/tools/3d-scenes#pro_3d_render)는 `generate_3d_scene`의 옵션이 아니라 별도의 기능입니다. 작업 하나가 완성된 샷을 만듭니다. 완료된 출력에는 `scenePlan`과 `videoUrl`이 모두 들어 있고, 리비전, 포스터, 검증 결과, 렌더러 세부 정보도 함께 옵니다. 이 도구는 이를 구현한 엔진이 있는 배포 환경에서만 나타나므로, 도구 목록에 있는지가 곧 사용 가능 여부를 확인하는 방법입니다. [**3D 렌더링 Pro**](https://nodaro.ai/docs/nodes/video/pro-3d-render) 노드처럼 작동합니다.

출력에는 `shotStills`도 들어 있습니다. 구성의 샷마다 스틸 이미지 한 장을 샷 순서대로 담으며, 형식은 `{ shotIndex, frame, assetId, url }`입니다. `shotIndex`는 0부터 세고 `frame`은 샷의 첫 프레임이므로, 스틸 이미지가 MP4와 정확히 맞습니다. 샷이 하나인 장면에는 프레임 0의 스틸 이미지가 정확히 한 장 있습니다. 스틸 이미지는 같은 실행에서 추가 비용 없이 만들어집니다. 동영상 모델로 어떤 샷을 생성할 때 그 샷의 스틸 이미지를 이미지 레퍼런스로 사용하세요.

전달 파일은 비공개이므로, 각 스틸 이미지의 `url`은 설치에서 인증이 필요한 주소입니다. 내 자격 증명으로 가져오세요. 공개 링크가 아닙니다. 그래도 이 URL을 `generate_image`나 `generate_video`에 전달할 수 있습니다. 그 실행은 그 파일 하나를 읽을 수 있는 짧은 권한을 받습니다. 이 권한은 몇 분 동안만 유지되고 저장되지 않으므로, 저장하는 모든 곳에는 인증이 필요한 URL을 남기세요.

더 저렴하고 편집 가능한 클레이 프리비즈에는 `generate_3d_scene`, `edit_3d_scene`, `render_3d_scene`을 사용하세요. 정확한 장면 형식과 현재 기본값을 알아보려면 `generate-3d-scene` 또는 `edit-3d-scene`으로 `get_node_skill`을 호출해 달라고 어시스턴트에게 요청하세요.

## 자주 묻는 질문

### Nodaro의 3D 장면이란 무엇인가요?

단순한 도형과 키프레임 움직임으로 이루어진, 편집 가능한 애니메이션 클레이 장면입니다. 프롬프트와 선택적인 레퍼런스로 작성합니다. 말로 하는 지시나 정확한 연산으로 수정하고, MP4로 렌더링합니다.

### 3D 장면 렌더링은 어디에 쓰나요?

동영상 모델의 레이아웃과 움직임 가이드로 씁니다. 렌더링을 레퍼런스 동영상으로 generate_video에 전달하고, 레이아웃 가이드라고 밝히는 캡션과 외형 레퍼런스를 함께 넘기세요.

### 3D 장면 렌더링은 크레딧이 얼마나 드나요?

가장 긴 변이 1920픽셀 이하인 프레임은 55크레딧, 그보다 크고 5.12메가픽셀 이하인 프레임은 83크레딧, 그보다 큰 프레임은 138크레딧입니다. 2560×2560 장면은 1920×1080 장면의 2.5배 비용이 듭니다.

### 장면 작업이 검토 경고와 함께 완료되었습니다. 문제가 있는 건가요?

아니요. 작업은 완료되었고 장면은 사용할 수 있습니다. metadata.review는 시각적 검토가 장면을 승인하지 않았다는 뜻입니다. 판정이 refused이면 검토가 이의를 제기한 것이고, unavailable이면 아무도 장면을 판단하지 않은 것입니다.

### 장면 작업이 실패했습니다. 다시 실행해야 하나요?

먼저 출력을 확인하세요. 고급 엔진에서 실패한 작업에도 편집하거나 렌더링할 수 있는 초안 장면이나, 거부된 레시피가 남아 있을 수 있습니다. 같은 프롬프트를 다시 실행하면 같은 작성 비용을 두 번 냅니다.