동영상 생성

"status"는 현재 세션 작업을 반환하고, "list"는 제공자를 조회합니다.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRpbWVvdXRNcyIgdHlwZT0ibnVtYmVyIg 밀리초 단위의 선택적 제공자 작업 시간 제한입니다. 생략하면 OpenClaw는 구성된 경우 agents.defaults.videoGenerationModel.timeoutMs를 사용하고, 그렇지 않으면 존재하는 경우 Plugin에서 작성한 제공자 기본값을 사용합니다. OPENCLAW_DOCS_MARKER:paramClose:

참조 입력에 따라 런타임 모드가 선택됩니다.

• 참조 미디어 없음 -> generate
• 이미지 참조가 하나라도 있음 -> imageToVideo
• 동영상 참조가 하나라도 있음 -> videoToVideo
• 참조 오디오 입력은 확정된 모드를 변경하지 않습니다. 이미지/동영상 참조가 선택한 모드에 추가로 적용되며, maxInputAudios를 선언한 제공자에서만 작동합니다.

이미지와 동영상 참조의 혼합은 안정적으로 공유되는 기능 인터페이스가 아닙니다. 요청마다 하나의 참조 유형만 사용하는 것이 좋습니다.

폴백 및 형식화된 옵션

일부 기능 검사는 도구 경계가 아니라 폴백 계층에서 적용되므로, 기본 제공자의 제한을 초과하는 요청도 해당 기능을 갖춘 폴백에서 실행될 수 있습니다.

• 요청에 오디오 참조가 있을 때 활성 후보가 maxInputAudios를 선언하지 않았거나 0을 선언했다면 해당 후보를 건너뛰고 다음 후보를 시도합니다. 이미지 및 동영상 참조 개수에도 maxInputImages/maxInputVideos를 기준으로 동일한 보호 규칙이 적용됩니다.
• 활성 후보의 maxDurationSeconds가 요청된 durationSeconds보다 작고 선언된 supportedDurationSeconds 목록이 없으면 건너뜁니다.
• 요청에 providerOptions가 있고 활성 후보가 형식화된 providerOptions 스키마를 명시적으로 선언한 경우, 제공된 키가 스키마에 없거나 값의 유형이 일치하지 않으면 건너뜁니다. 선언된 스키마가 없는 제공자는 옵션을 그대로 받습니다(이전 버전과 호환되는 그대로 전달 방식). 제공자는 빈 스키마 (capabilities.providerOptions: {})를 선언하여 모든 제공자 옵션을 거부할 수 있으며, 이 경우 유형 불일치와 동일하게 건너뜁니다.

요청에서 처음 발생한 건너뛰기 사유는 운영자가 기본 제공자가 제외된 시점을 확인할 수 있도록 warn 수준으로 기록됩니다. 이후의 건너뛰기는 긴 폴백 체인에서 로그가 과도해지지 않도록 debug 수준으로 기록됩니다. 모든 후보를 건너뛴 경우 집계된 오류에 각 후보의 건너뛰기 사유가 포함됩니다.

작업

모델 선택

OpenClaw는 다음 순서로 모델을 결정합니다.

1. model 도구 매개변수 - 에이전트가 호출에서 지정한 경우.
2. 구성의 videoGenerationModel.primary.
3. 순서대로 videoGenerationModel.fallbacks.
4. 자동 감지 - 유효한 인증이 있는 제공자를 대상으로 현재 기본 제공자부터 시작한 다음, 나머지 제공자를 알파벳순으로 확인합니다.

제공자가 실패하면 다음 후보를 자동으로 시도합니다. 모든 후보가 실패하면 오류에 각 시도의 세부 정보가 포함됩니다.

명시적인 model, primary, fallbacks 항목만 사용하려면 agents.defaults.mediaGenerationAutoProviderFallback: false로 설정하세요.

{  agents: {    defaults: {      videoGenerationModel: {        primary: "google/veo-3.1-fast-generate-preview",        fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],        timeoutMs: 180000, // 선택적 도구별 제공자 요청 시간 제한 재정의      },    },  },}

제공자 참고 사항

제공자 기능 모드

공유 비디오 생성 계약은 평면적인 전체 제한만 사용하는 대신 모드별 기능을 지원합니다. 새 제공자 구현에서는 명시적인 모드 블록을 우선 사용해야 합니다.

capabilities: {  generate: {    maxVideos: 1,    maxDurationSeconds: 10,    supportsResolution: true,  },  imageToVideo: {    enabled: true,    maxVideos: 1,    maxInputImages: 1,    maxInputImagesByModel: { "provider/reference-to-video": 9 },    maxDurationSeconds: 5,  },  videoToVideo: {    enabled: true,    maxVideos: 1,    maxInputVideos: 1,    maxDurationSeconds: 5,  },}

maxInputImages 및 maxInputVideos와 같은 평면적인 전체 필드만으로는 변환 모드 지원을 알리기에 충분하지 않습니다. 실시간 테스트, 계약 테스트, 공유 video_generate 도구가 모드 지원을 결정적으로 검증할 수 있도록 제공자는 generate, imageToVideo, videoToVideo를 명시적으로 선언해야 합니다.

제공자 내 모델 하나가 나머지 모델보다 더 폭넓은 참조 입력을 지원하는 경우, 모드 전체 제한을 높이는 대신 maxInputImagesByModel, maxInputVideosByModel 또는 maxInputAudiosByModel을 사용하세요.

실시간 테스트

공유 번들 제공자를 위한 선택적 실시간 테스트 범위:

OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts

저장소 래퍼:

pnpm test:live:media video

이 실시간 테스트 파일은 기본적으로 저장된 인증 프로필보다 이미 내보낸 제공자 환경 변수를 우선 사용하며, 기본적으로 릴리스에 안전한 스모크 테스트를 실행합니다.

• 점검 대상의 FAL 이외 모든 제공자에 대해 generate를 실행합니다.
• 1초 길이의 바닷가재 프롬프트를 사용합니다.
• 제공자별 작업 제한 시간은 OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS에서 가져옵니다(기본값 180000).

제공자 측 대기열 지연 시간이 릴리스 시간을 좌우할 수 있으므로 FAL은 선택적으로 실행됩니다.

pnpm test:live:media video --video-providers fal

OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1을 설정하면 공유 점검에서 로컬 미디어로 안전하게 실행할 수 있는 선언된 변환 모드도 실행합니다.

• capabilities.imageToVideo.enabled인 경우 imageToVideo.
• capabilities.videoToVideo.enabled이고 제공자/모델이 공유 점검에서 버퍼 기반 로컬 비디오 입력을 허용하는 경우 videoToVideo.

현재 공유 videoToVideo 실시간 테스트 경로는 runway/gen4_aleph를 선택한 경우에만 runway를 지원합니다.

구성

OpenClaw 구성에서 기본 비디오 생성 모델을 설정합니다.

{  agents: {    defaults: {      videoGenerationModel: {        primary: "qwen/wan2.6-t2v",        fallbacks: ["qwen/wan2.6-r2v-flash"],      },    },  },}

또는 CLI를 사용합니다.

openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"

관련 문서

• Alibaba Model Studio
• 백그라운드 작업 - 비동기 비디오 생성을 위한 작업 추적
• BytePlus
• ComfyUI
• 구성 참조
• fal
• Google (Gemini)
• MiniMax
• 모델
• OpenAI
• Qwen
• Runway
• Together AI
• 도구 개요
• Vydra
• xAI