adolf/docs/providers/pixverse.md

summary, title, read_when

summary	title	read_when
PixVerse video generation setup in OpenClaw	PixVerse	You want to use PixVerse video generation in OpenClaw You need the PixVerse API key/env setup You want to make PixVerse the default video provider

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

Getting started

```bash openclaw plugins install @openclaw/pixverse-provider openclaw gateway restart ``` ```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.videoGenerationModel.primary` to
`pixverse/v6` when no default video model is configured yet.

```bash openclaw config set agents.defaults.videoGenerationModel.primary "pixverse/v6" ``` 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_generate` yet. 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

Configuration

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "pixverse/v6",
      },
    },
  },
}

Advanced configuration

| 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: [],
      },
    },
  },
}
```

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",
      },
    },
  },
}
```

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.videoGenerationModel.timeoutMs`).

Related

Shared tool parameters, provider selection, and async behavior. Agent default settings including video generation model.