PixVerse Provider
기준일: 2026-07-26
난이도: 중급
공식 기준: PixVerse
개요
이 페이지는 OpenClaw PixVerse provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.
공식 요약: PixVerse video generation setup in OpenClaw
model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.
빠른 참조
| Property | Value |
|---|---|
| Provider id | pixverse |
| Plugin package | @openclaw/pixverse-provider |
| Auth env var | PIXVERSE_API_KEY |
| Onboarding flag | --auth-choice pixverse-api-key |
| Direct CLI flag | --pixverse-api-key <key> |
| API | PixVerse Platform API v2 (video_id submission plus result polling) |
| Default model | pixverse/v6 |
| Default API region | International |
공식 문서 기반 상세
아래는 공식 providers/pixverse 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.
OpenClaw provides pixverse as an official external plugin for hosted PixVerse video generation. The plugin registers the pixverse provider against the videoGenerationProviders contract.
| Property | Value |
|---|---|
| Provider id | pixverse |
| Plugin package | @openclaw/pixverse-provider |
| Auth env var | PIXVERSE_API_KEY |
| Onboarding flag | --auth-choice pixverse-api-key |
| Direct CLI flag | --pixverse-api-key <key> |
| API | PixVerse Platform API v2 (video_id submission plus result polling) |
| Default model | pixverse/v6 |
| Default API region | International |
시작하기
Install the plugin
```bash
openclaw plugins install @openclaw/pixverse-provider
openclaw gateway restart
```
Set the API key
```bash
openclaw onboard --auth-choice pixverse-api-key
```
The wizard prompts for the International or CN endpoint (see API region
below) before writing `region` and `baseUrl` into the provider config.
Non-interactive runs (key from `--pixverse-api-key` or `PIXVERSE_API_KEY`)
default to International.
Onboarding also sets `agents.defaults.mediaModels.video.primary` to
`pixverse/v6` when no default video model is configured yet.
Switch an existing default video provider (optional)
```bash
openclaw config set agents.defaults.mediaModels.video.primary "pixverse/v6"
```
Generate a video
Ask the agent to generate a video. PixVerse will be used automatically.
Supported modes and models
The provider exposes PixVerse generation models through OpenClaw's shared video tool.
| Mode | Models | Reference input |
|---|---|---|
| Text-to-video | v6 (default), c1 |
None |
| Image-to-video | v6 (default), c1 |
1 local or remote image |
Local image references are uploaded to PixVerse before the image-to-video request. Remote image URLs are passed through the PixVerse image upload endpoint as image_url.
| Option | Supported values |
|---|---|
| Duration | 1-15 seconds (default 5) |
| Resolution | 360P, 540P, 720P, 1080P (default 540P; 480P requests map to 540P) |
| Aspect ratio | 16:9 (default), 4:3, 1:1, 3:4, 9:16, 2:3, 3:2, 21:9; text-to-video only, image-to-video follows the source image |
| Generated audio | audio: true |
PixVerse image template generation is not exposed through
image_generateyet. That API is template-id driven, while OpenClaw's shared image-generation contract does not currently have a PixVerse-specific typed option bag.
Provider options
The video provider accepts these optional provider-specific keys:
| Option | Type | Effect |
|---|---|---|
seed |
number | Deterministic seed, 0 to 2147483647 |
negativePrompt / negative_prompt |
string | Negative prompt |
quality |
string | PixVerse quality such as 720p |
motionMode / motion_mode |
string | Image-to-video motion mode (default normal) |
cameraMovement / camera_movement |
string | PixVerse camera movement preset |
templateId / template_id |
number | Activated PixVerse template id |
설정
{
agents: {
defaults: {
videoGenerationModel: {
primary: "pixverse/v6",
},
},
},
}
고급 설정
API region
| Region value | PixVerse API base URL |
| --------------- | --------------------------------------------- |
| `international` | `https://app-api.pixverse.ai/openapi/v2` |
| `cn` | `https://app-api.pixverseai.cn/openapi/v2` |
Set `models.providers.pixverse.region` manually when your key belongs to a
specific PixVerse platform region, or run
`openclaw onboard --auth-choice pixverse-api-key` to choose one in the
setup wizard:
```json5
{
models: {
providers: {
pixverse: {
region: "cn", // "international" or "cn"
baseUrl: "https://app-api.pixverseai.cn/openapi/v2",
models: [],
},
},
},
}
```
Custom base URL
Set `models.providers.pixverse.baseUrl` only when routing through a trusted compatible proxy.
`baseUrl` takes precedence over `region`.
```json5
{
models: {
providers: {
pixverse: {
baseUrl: "https://app-api.pixverse.ai/openapi/v2",
},
},
},
}
```
Task polling
PixVerse returns a `video_id` from the generation request. OpenClaw polls
`/openapi/v2/video/result/{video_id}` every 5 seconds until the task
succeeds, fails, or hits the timeout (default 5 minutes; override with
`agents.defaults.mediaModels.video.timeoutMs`).
관련 문서
Shared tool parameters, provider selection, and async behavior.
Agent default settings including video generation model.
검증 체크리스트
-
openclaw models list --provider pixverse로 모델이 보이는지 확인 - 기본 model alias를
agents.defaults.model.primary에 설정했는지 확인 - API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
- failover 시 데이터가 다른 provider로 이동할 수 있는지 검토