동영상 및 오디오 생성
Libre WebUI 0.18.0은 이미지 너머로 생성 기능을 확장합니다. 공급자 플러그인이 동영상 및 오디오 기능을 선언할 수 있고 이미지, 동영상, 음성, 사운드 등 생성된 모든 항목이 사용자별 미디어 갤러리 하나에 저장됩니다.
인증된 모든 사용자가 미디어 생성을 이용할 수 있습니다. 갤러리는 엄격하게 사용자별로 분리됩니다. 모든 읽기, 콘텐츠 가져오기와 삭제는 로그인한 계정 범위로 제한됩니다.
플러그인 기능 블록
플러그인 정의에서는 각 미디어 기능을 개별 블록으로 선언합니다.
"capabilities": {
"image": { "endpoint": "...", "model_map": ["..."], "config": { ... } },
"tts": { "endpoint": "...", "model_map": ["..."], "config": { ... } },
"audio": { "endpoint": "...", "model_map": ["..."], "config": { ... } },
"video": { "endpoint": "...", "model_map": ["..."], "config": { ... } }
}
모든 블록에는 endpoint, 대체 목록인 model_map, 실시간 모델 검색을 위한 선택적 models_endpoint, 기능별 옵션이 담긴 config 객체가 있습니다. 이미지의 크기와 화면 비율, 음성의 보이스와 형식, 동영상의 해상도, 화면 비율과 길이 등이 이에 해당합니다. 동영상 공급자는 프롬프트 ID 기반 cancel_endpoint와 cancel_method를 선언할 수도 있습니다. Libre는 일반 생성 엔드포인트에서 취소 지원 여부를 추론하지 않습니다.
두 가지 오디오 기능이 있으며 둘 다 오디오로 갤러리에 저장됩니다.
tts는 음성입니다. 선택한 보이스로 텍스트를 읽습니다.audio는 사운드입니다. 모델이 프롬프트에서 오디오 콘텐츠를 생성합니다.
현재 video와 audio 블록을 선언하는 번들 플러그인은 OpenRouter(plugins/openrouter.json)뿐입니다. models_endpoint가 있으면 일반 검색 주기에 모델 목록을 새로 고칩니다(검색 TTL 설정은 환경 변수 참조). model_map은 대체 값으로 유지됩니다.
미디어 생성하기
Imagine(/gallery)을 엽니다. 헤더에서는 이미지 생성이 설정에서 활성화된 경우 이미지용 생성과 함께 동영상, 오디오 패널을 제공합니다.
음성과 사운드 생성은 동기식입니다. 요청을 실행해 결과를 갤러리에 저장한 뒤 완성된 항목을 응답으로 반환합니다. 취소를 누르면 브라우저 요청과 Libre의 외부 공급자 요청이 중단되고 취소된 결과는 저장되지 않습니다. 이미지 생성도 같은 연결 해제 취소 계약을 따릅니다.
승인된 ComfyUI 작업 흐름의 경우 Libre는 프롬프트 ID 작업 취소 작업과 프롬프트 ID 큐 삭제를 모두 보내고, 요청을 해제하기 전에 이 정리가 완료되도록 최대 3초 동안 기다립니다. 다른 사용자의 작업 흐름을 중지할 수 있는 ComfyUI의 범위 없는 중단 작업은 절대 호출하지 않습니다. 현재 ComfyUI 릴리스는 실행 중인 작업 흐름에 /api/jobs/:promptId/cancel을 제공합니다. 이 작업이 없는 이전 릴리스에서도 Libre는 정확한 대기 중 큐 항목을 제거할 수 있지만 이미 실행 중인 작업 흐름은 안전하게 중지할 수 없습니다. 완전한 취소 계약을 사용하려면 ComfyUI를 업그레이드하세요.
TTS 플러그인은 음성 복제를 선언할 수도 있습니다. 이러한 모델을 사용하면 오디오 패널에 참조 오디오 업로드가 표시되고 공급자에서 요구하는 경우 정확한 대본 필드도 표시됩니다. Libre WebUI는 매니페스트의 파일 유형과 크기 한도를 검증하고 업로드를 메모리에 보관한 뒤 선택한 공급자에만 전달합니다. 생성된 음성만 갤러리에 저장됩니다.
복제된 음성은 같은 플러그인과 모델에서 재사용 가능한 이름 있는 보이스로 선택적으로 저장할 수 있습니다. 저장하려면 별도의 저장 동의 확인이 필요합니다. Libre WebUI는 원본 참조와 대본을 사용자 소유 보이스 프로필에 암호화하며, 생성된 음성을 참조로 사용하지 않습니다. 저장된 프로필은 설정 → 텍스트 음성 변환에서 선택하거나 영구적으로 삭제할 수 있습니다. 음성 배치를 생성할 때마다 구성된 공급자가 저장된 참조를 다시 받습니다. 프로필은 해당 공급자의 승인된 라우팅에 바인딩됩니다. 플러그인 정의나 엔드포인트가 바뀌면 새 대상에 동의할 수 있도록 프로필을 다시 만드세요. 복제 요청과 요청된 저장에 모두 동의한 화자의 녹음만 사용하세요.
보이스 프로필은 생체 인식 원본 자료를 포함하므로 Libre WebUI의 일반 데이터 내보내기에서 의도적으로 제외됩니다. 재해 복구가 필요하면 암호화된 애플리케이션 데이터베이스와 ENCRYPTION_KEY를 함께 백업하세요. 그렇지 않으면 동의를 받은 원본 녹음으로 프로필을 다시 만드세요.
동영상 작업 수명 주기
동영상 생성은 비동기식입니다. 작업을 제출하면(POST /api/media/video/generate) 작업 레코드와 함께 202가 반환되며 작업은 pending, in_progress를 거쳐 최종적으로 completed 또는 failed 상태가 됩니다.
- 제출은 검증 후 브라우저 응답에서 분리됩니다. 공급자가 응답하는 동안 패널이나 네트워크 연결이 닫혀도 Libre는 승인 직후 공급자 작업 ID를 저장합니다.
GET /api/media/video/jobs는 인증된 사용자가 저장한 핸들만 나열하며, 패널이 열릴 때마다 활성 핸들을 최대 100개 요청합니다. 따라서 탐색, 새로 고침 또는 연결 해제 후에도 대기 중인 작업을 다시 열 수 있습니다.- 영구
media.video.resume.v1작업은 패널이 닫혀 있어도 공급자를 폴링하고 완료된 결과를 다운로드합니다. solo 모드는 임베디드 워커에서, team 모드는 외부 워커에서 해당 처리기를 실행합니다. 임대, 제한된 재시도, 행위자 재검증과 조건부 완료를 통해 프로세스가 종료되어도 다른 워커가 중복 갤러리 행이나 Blob 참조를 만들지 않고 작업을 회수할 수 있습니다. 기존 resume/GET 엔드포인트는 호환성 및 상태 경계로 유지되며 UI가 표시를 위해 계속 폴링할 수 있습니다. - 패널을 닫거나 대기 중지를 선택하면 현재 상태 또는 다운로드 전송만 중단됩니다. 공급자 측 작업 취소 작업은 플러그인에서 작업 ID 취소 엔드포인트를 명시적으로 선언한 경우에만 나타납니다. 공급자 취소가 확인되면 Libre가 저장된 로컬 핸들을 제거합니다.
- 완료되면 백엔드에서 동영상을 다운로드하고(200 MB 한도, HTTP 리디렉션을 따르지 않음) 갤러리에 저장합니다.
- 작업 레코드에는 플러그인, 모델, 옵션, 상태와 프롬프트가 저장되며 프롬프트는 저장 시 암호화됩니다. 완료되거나 실패한 지 30일이 지난 작업 레코드는 기회적으로 정리되지만 대기 중인 핸들은 이 정리로 만료되지 않습니다.
- 종료 상태는 알림을 보냅니다. 완료된 동영상은 media-ready, 공급자 실패는 media-failed 알림을 게시합니다. 둘 다 갤러리로 연결되고 작업별로 중복 제거되며 앱 내 받은 편지함과 구독한 Webhook을 통해 전달됩니다.
이미지 편집과 인페인팅
편집 가능한 모델을 구성하면 갤러리 이미지에 이미지 편집 작업이 추가됩니다. 편집기는 이미지 위에 직접 마스크를 칠합니다. 칠한 영역은 모델이 다시 그리며, 캔버스를 건드리지 않으면 전체 이미지를 편집합니다. 모델에서 둘 이상의 입력을 허용하면 합성을 위한 참조 이미지를 추가로 첨부할 수 있습니다. 편집은 OpenAI 호환 멀티파트 편집 계약을 사용합니다. 플러그인이 참여하려면 이미지 기능 구성에 edit_endpoint를 선언하고 선택적으로 supports_mask, max_reference_images, edit_mime_types, max_edit_image_bytes 한도를 지정합니다. 번들 OpenAI 매니페스트는 이 항목을 모두 선언합니다.
바이트가 프로세스를 떠나기 전에 모든 입력을 검증합니다. 선언된 MIME, 감지한 매직 바이트(PNG, JPEG 또는 WebP), 이미지당 10 MiB 한도를 확인합니다. 다시 그릴 영역을 나타내는 알파 채널은 PNG만 지원하므로 마스크는 PNG여야 합니다. 결과는 원본 갤러리 항목, 업로드한 참조 이미지 수와 마스크 사용 여부를 기록하는 출처 메타데이터와 함께 갤러리에 다시 저장됩니다. 편집 사용량은 생성과 똑같이 계측됩니다.
통합 갤러리
갤러리는 모든 미디어 유형을 생성 시간 순으로 섞어 나열하고 전체, 이미지, 동영상, 오디오 필터를 제공합니다. 동영상과 오디오는 인라인으로 재생되고 이미지는 라이트박스에서 열리며 모든 항목을 다운로드하거나 삭제할 수 있습니다. 관리자는 GALLERY_RETENTION_DAYS를 사용해 자동 보존을 선택할 수 있습니다. 스케줄러 정리는 수동 삭제와 같은 영구 삭제 수명 주기를 통해 보존 기간보다 오래된 미디어를 삭제합니다. 설정하지 않은 기본 상태에서는 소유자가 삭제할 때까지 미디어를 유지합니다.
저장과 제공은 의도적으로 보수적으로 설계되었습니다.
- 미디어는 디스크에 개별 파일로 저장되지 않고 애플리케이션 데이터베이스(
DATA_DIR아래)에서 암호화됩니다. 모든 암호화 데이터와 마찬가지로 데이터베이스와ENCRYPTION_KEY를 함께 백업하세요. - API 응답에는 미디어 페이로드를 포함하지 않으며 항목별 콘텐츠 URL을 참조합니다.
- 제공되는 콘텐츠는 미디어 유형별 MIME 허용 목록 및 저장된 유형과 일치해야 하고 200 MB로 제한되며, 응답을 샌드박스 처리하는
X-Content-Type-Options: nosniff와Content-Security-Policy를 적용해 전달됩니다.
이전 이미지 전용 엔드포인트와 이미지 생성 패널은 변경 없이 계속 작동하며 같은 갤러리에 기록합니다.
속도 제한
미디어 API는 클라이언트별로 속도가 제한됩니다.
| 작업 | 한도 |
|---|---|
| 생성(동영상, 음성, 사운드) | 분당 요청 10회 |
| 동영상 작업 폴링 | 분당 요청 60회 |
| 갤러리 목록, 콘텐츠와 삭제 | 분당 요청 120회 |
UI의 30초 폴링은 폴링 한도보다 충분히 낮습니다.
계측과 개인정보 보호
미디어 생성 호출은 다른 모든 외부 공급자 호출처럼 관리자의 사용량 분석에 계측됩니다. 플러그인, 모델, 상태, 지속 시간과 단위 수가 기록됩니다. 프롬프트와 생성 콘텐츠는 사용량 레코드에 절대 기록되지 않습니다. 생성된 미디어와 동영상 작업 프롬프트는 사용자 본인의 암호화된 행에만 존재합니다.
채팅과 마찬가지로 구성된 공급자는 프롬프트를 받아 콘텐츠를 반환하므로 공급자의 요금, 보존 및 콘텐츠 정책이 적용됩니다.