참고 파일 올리기
이미지·비디오 만들기에 참고 파일을 넣는 방법, 지원 형식과 크기, 외부 도구의 업로드 경로입니다.참고 파일이란
이미지나 비디오를 만들 때 "이 그림처럼", "이 사진에서 시작해서"처럼 기준이 될 파일을 함께 넣을 수 있습니다. 넣은 파일은 먼저 에셋으로 저장되고, 만들기는 에셋을 가리키는 방식으로 파일을 씁니다. 그래서 한 번 올린 파일은 다시 올리지 않고 에셋에서 골라 쓸 수 있습니다.
넣을 수 있는 파일은 만드는 종류와 모델이 정합니다. 모델이 받지 않는 칸은 화면에 나오지 않습니다.
지원 형식과 크기
| 쓰는 곳 | 받는 형식 | 최대 개수 |
|---|---|---|
| 이미지 만들기의 레퍼런스 | PNG, JPEG, WebP | 모델마다 다르며 최대 5장 |
| 비디오 만들기의 첫 프레임, 끝 프레임 | PNG, JPEG, WebP | 각 1장 |
| 비디오 만들기의 레퍼런스 | 이미지는 PNG, JPEG, WebP, 비디오는 MP4, WebM, MOV, 오디오는 MP3, WAV, MP4 오디오(M4A), OGG, FLAC, AAC. 이 중 모델이 받는 종류만 | 모델마다 다르며 모델이 정하지 않으면 9개 |
| 비디오 만들기의 편집할 영상 | MP4, WebM, MOV | 1개 |
| 에셋 보관함에 올리기 | 이미지(PNG, JPEG, WebP), 오디오, 비디오 | 한 번에 여러 개 |
- 파일 하나의 최대 크기는 20MB입니다. 넘으면 "파일이 너무 커요. 최대 20MB까지 올릴 수 있어요."가 나옵니다.
- 형식은 파일 이름이 아니라 내용으로 판별합니다. 확장자가 맞아도 내용이 다르면 거절됩니다.
- 이미지는 움직이는 이미지(애니메이션)를 올릴 수 없고, 가로×세로가 4천만 화소를 넘으면 거절됩니다. 손상된 이미지도 거절됩니다.
- 같은 칸에 넣을 수 있는 장수를 넘으면 "최대 N개까지 넣을 수 있어요"가 나옵니다.
- 이미지 생성에는 이미지 에셋만 붙일 수 있습니다. 다른 종류를 붙이면 "이미지 생성에는 이미지 에셋만 첨부할 수 있어요."가 나옵니다.
화면에서 넣기
이미지 만들기에서
입력창에 레퍼런스 추가(+)와 요소 추가(@) 버튼이 있습니다. 둘은 같은 레퍼런스 고르기 패널을 다른 탭으로 엽니다. 모델이 참조 이미지를 받지 않으면 두 버튼이 나오지 않습니다.
패널의 탭은 다음과 같습니다.
| 탭 | 보이는 것 |
|---|---|
| 업로드 | 이미지 올리기 타일과, 이전에 올린 이미지 |
| 캐릭터 | 내 캐릭터. 새 캐릭터로 이름과 사진 한 장을 바로 등록해 쓸 수도 있습니다. |
| 내 에셋 | 에셋에 있는 이미지 전부 |
| 생성물 | 내가 만든 이미지 |
| 요소 | 용도를 붙여 둔 에셋. 전체, 일반, 캐릭터, 배경, 소품으로 거릅니다. |
타일을 눌러 고르고, 다시 누르면 뺍니다. 즐겨찾기만 보기로 즐겨찾기한 것만 볼 수 있습니다. 목록이 길면 더 보기를 누릅니다. 몇 장을 골랐는지는
현재/최대로 보입니다.패널 없이도 넣을 수 있습니다.
- 입력창에 파일을 끌어다 놓습니다. 끌고 있는 동안 "여기에 놓으면 레퍼런스로 추가돼요"가 나옵니다.
- 이미지 파일을 복사해 입력창에 붙여 넣습니다.
넣은 파일은 입력창 위에 칩으로 쌓입니다. 칩의 이름 버튼에서 레퍼런스 역할 바꾸기(일반, 배경, 소품, 캐릭터)를 하고, 빼기 버튼으로 뺍니다. 캐릭터 역할은 출연진을 함께 골라야 합니다. 출연진을 고르지 않으면 "캐릭터 역할 참조 N장의 출연진을 골라 주세요"가 나오고 생성이 막힙니다.
파일을 넣으면 자동으로 에셋에 저장됩니다. 올리는 동안은 올리는 중이 보입니다.
비디오 만들기에서
모델이 받는 칸(첫 프레임, 끝 프레임, 레퍼런스, 편집할 영상)이 입력창 아래에 나옵니다. 각 칸의 메뉴에서 고릅니다.
- 올리기: 내 컴퓨터에서 파일을 고릅니다. 칸이 받는 형식만 파일 선택 창에 보입니다.
- 에셋 고르기: 내 에셋 중 그 칸이 받는 종류만 보이는 선택 창이 열립니다.
칸의
현재/최대와 필수/선택 표시, 규칙은 비디오 만들기에 있습니다.에셋에서 먼저 올리기
에셋 화면(
/assets)의 업로드 버튼으로 이미지, 오디오, 비디오를 올릴 수 있습니다. 올린 결과는 업로드 결과에 진행률과 업로드 완료, 업로드 실패로 보이고 다시 올리기를 할 수 있습니다. 형식이 맞지 않으면 "지원하지 않는 파일 형식이에요"가 나옵니다. 올려 둔 파일은 만들기의 내 에셋 탭이나 에셋 고르기에서 고릅니다.외부 연결(MCP·API)에서 올리기
외부 도구는 파일을 올린 뒤 그 에셋을 가리키는 방식으로 씁니다. 에셋 참조는
assetId와 revision으로 이루어집니다.공개 REST
POST /assets로 멀티파트 폼을 보냅니다. 키에 에셋 업로드 권한이 필요하고, 응답은 201과 에셋 정보입니다. 그 assetId와 revision을 이미지 접수의 referenceAssets에 넣습니다(최대 5개). 폼 필드, 예시 코드, 시간당 120회 한도는 레시피의 "업로드한 파일 쓰기"와 API 레퍼런스에 있습니다.- 개인 키로 부를 수 있는 업로드 경로는
POST /assets하나입니다. 같은 경로의 나머지 에셋 관리 경로는 로그인 세션 전용입니다. - 폼에
file,name,folderId,role,tags외의 필드를 보내거나 파일이 둘 이상이면 400입니다. - 크기와 형식 규칙은 위 지원 형식과 크기 절과 같습니다.
MCP
대화형 AI 도구는 파일을 HTTP로 직접 보낼 수 없어서, 스튜디오 서버(
/studio/mcp)의 studio_upload로 올립니다. 이미지(PNG, JPEG, WebP)만 됩니다. 체리를 쓰지 않으며 세 단계입니다.| 단계 | action | 하는 일 |
|---|---|---|
| 1 | begin | 이름, 형식, 전체 바이트 크기를 선언합니다. 서버는 크기(20MB)와 형식을 먼저 검사하고, 업로드 슬롯(uploadId)과 조각 계획(chunkSize, chunkCount)을 돌려줍니다. 슬롯은 900초 뒤 만료됩니다. |
| 2 | chunk | base64 조각을 하나씩 보냅니다. 한 조각은 최대 32KiB(32,768바이트)이고, 순서는 섞여도 됩니다. 같은 조각을 같은 데이터로 다시 보내면 그대로 받아들입니다. |
| 3 | complete | 조각을 모아 이미지 에셋으로 저장합니다. 선언한 형식과 실제 내용이 다르거나 이미지가 아니면 저장하지 않습니다. |
모든 단계에
idempotencyKey가 필요하고, 같은 키로 다시 부르면 같은 결과가 돌아옵니다. 20MB는 조각 640개 분량입니다. 완료 응답의 에셋은 image_generate의 referenceAssets나 sourceAsset에 씁니다. 영상은 문서 영상 노드의 참조로 넣습니다.이미 에셋에 있는 파일을 찾을 때는
studio_query의 assets(목록), asset(하나, 읽기 링크 900초), resolve_assets(여러 개 일괄)를 씁니다. assetId 자리에 @에셋 이름도 쓸 수 있고, 같은 이름이 여럿이면 후보 목록과 함께 ambiguous_asset_name이 돌아오니 사용자에게 어느 것인지 물으세요.연결 열쇠를 만들 때 에셋 업로드(REST)나 스튜디오 공통(MCP) 기능을 허용해야 합니다. 허용 범위는 연결과 인증에 있습니다.