# 3D 장면

> 프롬프트로 편집 가능한 클레이 장면을 만들고, 수정하고, MP4로 렌더링하거나, 작업 하나로 완성된 샷을 만드는 3D 장면 도구 4개의 매개변수입니다.

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

**3D 장면 도구**는 단순한 형태와 키프레임 움직임으로 이루어진, 편집 가능한 애니메이션 클레이 장면을 만들고, 수정하고, 동영상으로 렌더링합니다. 렌더링 결과는 동영상 모델의 레이아웃과 움직임 가이드로 쓸 수 있습니다. 이 페이지에는 각 도구의 매개변수가 나와 있습니다. 전체 흐름과 결과를 읽는 방법은 [3D 장면](https://nodaro.ai/docs/mcp/3d-scenes)에서 설명합니다.

모든 도구에는 `workflows:execute` 권한이 필요하며, 작업 ID를 반환합니다. 결과는 `get_job`이나 `wait_for_job`으로 읽으세요.

## `generate_3d_scene`
프롬프트와 선택 사항인 레퍼런스로 편집 가능한 애니메이션 클레이 장면을 만듭니다. 실사 동영상은 만들지 않습니다. [**3D 장면 생성**](https://nodaro.ai/docs/nodes/video/generate-3d-scene) 노드와 같은 방식으로 작동합니다.

**권한:** `workflows:execute`. **크레딧:** **3D 장면 생성** 노드와 같은 11~110크레딧입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `prompt` | string | **필수.** 샷의 설명으로, 최대 8,000자입니다. |
| `duration_seconds` | number | 1~60입니다. |
| `fps` | integer | 15~60입니다. |
| `aspect_ratio` | string | 프레임의 모양입니다. |
| `references` | array | 레퍼런스 최대 8개이며, 그중 동영상은 1개까지입니다. 각 레퍼런스는 `{ id, url, kind, role }`입니다. `kind`는 `image` 또는 `video`입니다. `role`은 `appearance`, `layout`, `motion` 중 하나로, 이미지는 외형과 레이아웃을, 동영상은 레이아웃과 움직임을 안내합니다. 동영상 레퍼런스는 전체가 사용되므로, 일부 구간만 쓰려면 먼저 잘라 내세요. 선택 사항인 `objectId`로 레퍼런스가 보여 주는 장면 오브젝트(예: 주인공)를 지정할 수 있습니다. |
| `input_assets` | array | 기존 3D 모델(GLB) 최대 8개이며, 각각 `{ id, revisionId, assetId, label }`입니다. 이를 가져올 수 있는 고급 엔진이 필요하며, 그렇지 않으면 요금이 청구되기 전에 호출이 거부됩니다. URL은 보내지 마세요. |
| `engine` | string | `basic`(기본값), `blender-cloud`, `blender-local` 중 하나입니다. 배포에 없는 엔진은 거부되며, `basic`으로 대체되지 않습니다. |
| `max_repair_passes` | integer | 고급 엔진의 수정 횟수 상한으로, 0~2입니다. |
| `llm_model`, `reasoning_effort` | string | `basic` 엔진의 플래너입니다. 고급 엔진은 고정된 플래너를 쓰므로 생략하세요. |
| `local_connection_id` | string | `blender-local`에서 쓰는, 페어링된 데스크톱 연결입니다. |
| `accepted_scene_schema_versions` | array | 내 클라이언트가 받아들이는 장면 형식 버전입니다. |

**반환값:** 작업 ID입니다. 완료된 작업의 `output_data.scenePlan`이 `revisionId`를 포함한 장면입니다.

## `edit_3d_scene`
장면을 수정하고 이전 리비전도 그대로 보관합니다. 플래너가 적용하는 프롬프트, 또는 LLM 호출 없이 바로 적용되는 연산 중 하나를 보내세요. [**3D 장면 편집**](https://nodaro.ai/docs/nodes/video/edit-3d-scene) 노드와 같은 방식으로 작동합니다.

**권한:** `workflows:execute`. **크레딧:** **3D 장면 편집** 노드와 같은 0~110크레딧입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `scene_plan` | object | **필수.** 장면 작업에서 받은 `scenePlan` 전체입니다. |
| `expected_revision_id` | string | **필수.** 플랜의 `revisionId`입니다. 일치하지 않으면 편집이 거부됩니다. |
| `prompt` | string | 변경 내용을 말로 쓴 것으로, 최대 8,000자입니다. |
| `operations` | array | 정확한 변경 1~100개입니다. `set-object`, `add-object`, `remove-object`, `set-camera`, `set-lighting`, `set-background` 중 하나입니다. |
| `locked_object_ids` | array | 편집에서 바꾸면 안 되는 오브젝트입니다. |
| `selected_object_ids` | array | 편집 대상인 오브젝트입니다. |
| `references` | array | `generate_3d_scene`과 같습니다. |
| `replace_references` | boolean | 장면의 이미지 레퍼런스와 동영상 레퍼런스를 `references`로 바꿉니다. |
| `engine`, `max_repair_passes`, `llm_model`, `reasoning_effort`, `local_connection_id`, `accepted_scene_schema_versions` | | `generate_3d_scene`과 같습니다. |

**반환값:** 작업 ID입니다. 완료된 작업의 `output_data`에는 새 `scenePlan`과 `changeSummary`가 들어 있습니다. MP4만으로는 편집 가능한 장면이 되지 않습니다. 동영상에서 장면을 다시 만들려면 그 동영상을 레퍼런스로 넣어 `generate_3d_scene`을 사용하세요.

## `render_3d_scene`
정확한 장면 리비전을 **동영상 렌더링** 엔진으로 MP4로 렌더링합니다. LLM은 실행되지 않습니다. 카메라, 길이, 프레임은 장면 플랜에서 가져옵니다.

**권한:** `workflows:execute`. **크레딧:** 플랜의 프레임 크기로 정해집니다. 긴 변이 1920픽셀 이하이면 55크레딧, 그보다 크고 5.12메가픽셀 이하이면 83크레딧, 그보다 큰 프레임은 138크레딧입니다.

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `scene_plan` | object | **필수.** 렌더링할 장면 플랜입니다. |

**반환값:** 작업 ID입니다. 결과는 동영상 URL입니다. 플랜의 `width`와 `height`는 의도한 값으로 설정하세요. 2560×2560 장면은 1920×1080 장면의 2.5배 가격이지만, 1920×1920은 1920×1080과 가격이 같습니다. 전체 가격표는 [**동영상 렌더링**](https://nodaro.ai/docs/nodes/video/render-video)에 있습니다.

## `pro_3d_render`
완성된 3D 샷을 작업 하나로 만듭니다. 완료된 작업에는 장면 플랜, MP4, 샷마다 스틸 이미지 1장이 담겨 있습니다. 이 도구는 해당 엔진이 있는 배포에서만 도구 목록에 나타납니다. [**3D 렌더링 Pro**](https://nodaro.ai/docs/nodes/video/pro-3d-render) 노드와 같은 방식으로 작동합니다.

**권한:** `workflows:execute`. **크레딧:** 같은 호출에서 견적을 내고 청구합니다. 장면 제작과 각 수정 패스는 유료 작업이며, 기존 장면을 그대로 내보내면 제작 비용이 들지 않습니다. **Nodaro Cloud 전용.**

| 매개변수 | 타입 | 설명 |
| --- | --- | --- |
| `source` | object | **필수.** 아래 소스 3가지 중 정확히 하나입니다. |
| `duration_seconds`, `fps` | number | 1~60초, 15~60fps입니다. 장면 소스에서는 타이밍을 바꾸려는 경우가 아니면 생략하세요. 충돌하는 값은 거부됩니다. |
| `aspect_ratio` | string | `16:9`, `9:16`, `1:1`, `4:5`, `21:9` 중 하나입니다. 장면 소스에서는 생략하세요. |
| `max_repair_passes` | integer | 수정 횟수 상한으로, 0~2입니다. 기본값은 `2`입니다. 수정 패스마다 요금이 청구됩니다. |
| `engine` | string | `blender-cloud` 또는 `blender-local`입니다. |
| `quality`, `style` | string | `standard`와 `clay`입니다. |
| `client_request_id` | string | 재시도 토큰으로, 영문자, 숫자, `_ - . :`로 이루어진 8~128자입니다. 타임아웃 후 재시도할 때 같은 값을 다시 쓰면 작업이 두 번 시작되거나 두 번 청구되지 않습니다. |

| `source.kind` | 필드 | 하는 일 |
| --- | --- | --- |
| `prompt` | `prompt`, 그리고 선택 사항인 `references`와 `input_assets` | 브리프로 새 장면을 제작한 다음 렌더링합니다. |
| `scene` | `revision_id`, 선택 사항인 `source_job_id`와 `edit_prompt` | 기존 리비전을 렌더링합니다. `edit_prompt`가 없으면 그대로 내보냅니다. 있으면 먼저 장면을 수정하므로 제작 비용이 듭니다. 작업 기록에만 남아 있는 `basic` 장면에는 `source_job_id`가 필요합니다. |
| `local-export` | `export_id`, `connection_id` | 사용할 수 있는 경우, 페어링된 데스크톱 앱에서 완료된 내보내기를 사용합니다. |

**반환값:** 작업 ID입니다. 완료된 작업의 `output_data`에는 `scenePlan`, `videoUrl`, `shotStills`가 담겨 있습니다. `shotStills`는 샷마다 스틸 이미지 1장이며, 각각 `{ shotIndex, frame, assetId, url }`입니다. 모델이나 추론 매개변수는 없습니다. 플래너는 고정되어 있습니다.

## 자주 묻는 질문

### 3D 장면을 렌더링하는 데 크레딧이 얼마나 드나요?

렌더링 가격은 장면 플랜의 프레임 크기로 정해집니다. 긴 변이 1920픽셀 이하이면 55크레딧, 그보다 크고 5.12메가픽셀 이하이면 83크레딧, 그보다 큰 프레임은 138크레딧입니다.

### 3D 장면을 편집하면 항상 AI 모델이 호출되나요?

아니요. 오브젝트 이동이나 카메라 변경 같은 연산으로 편집하면 LLM을 호출하지 않고 연산이 바로 적용됩니다. 프롬프트로 편집하면 플래너가 변경을 처리합니다.

### render_3d_scene과 pro_3d_render는 어떻게 다른가요?

render_3d_scene은 기존 장면 리비전을 MP4로 내보냅니다. pro_3d_render는 장면 제작, 수정, 내보내기를 작업 하나로 처리하며 장면 플랜, MP4, 샷마다 스틸 이미지 1장을 반환합니다. pro_3d_render는 해당 엔진이 있는 배포에서만 사용할 수 있습니다.