3D 장면

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

도구

각 도구에는 workflows:execute가 필요하며, 도구는 작업 ID를 반환합니다. 결과는 get_job 또는 wait_for_job으로 읽으세요. 장면 작업은 output_data.scenePlan을 반환하고, 렌더링은 동영상 URL을 반환합니다. 파라미터는 도구 레퍼런스에 있습니다.

기본 흐름

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

첫 버전에서 할 수 있는 것

• 도형과 움직임. 장면은 기본 도형과 결정론적인 키프레임 애니메이션을 사용합니다.
• 레퍼런스는 근사치입니다. 레퍼런스로 다시 만든 장면은 그 레퍼런스의 근사치입니다.
• 동영상 레퍼런스는 전체를 사용합니다. 동영상 레퍼런스는 통째로 사용됩니다. 일부 구간만 쓰려면 먼저 클립을 트리밍하고 트리밍한 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이나 해시는 절대 보내지 마세요.

렌더링 비용

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

장면 플랜의 width와 height는 의도해서 설정하세요. 2560×2560 장면은 1920×1080 장면의 2.5배 비용이 들지만, 1920×1920은 1920×1080과 비용이 같습니다. 전체 표는 동영상 렌더링에 있습니다.

고급 엔진의 결과 읽기

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

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

완료된 장면이 승인되지 않았을 때

완료된 작업에 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는 generate_3d_scene의 옵션이 아니라 별도의 기능입니다. 작업 하나가 완성된 샷을 만듭니다. 완료된 출력에는 scenePlan과 videoUrl이 모두 들어 있고, 리비전, 포스터, 검증 결과, 렌더러 세부 정보도 함께 옵니다. 이 도구는 이를 구현한 엔진이 있는 배포 환경에서만 나타나므로, 도구 목록에 있는지가 곧 사용 가능 여부를 확인하는 방법입니다. 3D 렌더링 Pro 노드처럼 작동합니다.

출력에는 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을 호출해 달라고 어시스턴트에게 요청하세요.