> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PixVerse

OpenClaw 提供 `pixverse` 作為官方外部外掛，用於託管的 PixVerse 影片生成。此外掛會依據 `videoGenerationProviders` 合約註冊 `pixverse` 提供者。

| 屬性        | 值                                             |
| --------- | --------------------------------------------- |
| 提供者 ID    | `pixverse`                                    |
| 外掛套件      | `@openclaw/pixverse-provider`                 |
| 驗證環境變數    | `PIXVERSE_API_KEY`                            |
| 導覽設定旗標    | `--auth-choice pixverse-api-key`              |
| 直接命令列介面旗標 | `--pixverse-api-key <key>`                    |
| API       | PixVerse Platform API v2（`video_id` 提交加上結果輪詢） |
| 預設模型      | `pixverse/v6`                                 |
| 預設 API 區域 | 國際                                            |

## 開始使用

<Steps>
  <Step title="安裝外掛">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins install clawhub:@openclaw/pixverse-provider
    openclaw gateway restart
    ```
  </Step>

  <Step title="設定 API 金鑰">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --auth-choice pixverse-api-key
    ```

    精靈會先詢問要使用國際端點
    (`https://app-api.pixverse.ai/openapi/v2`) 或 CN 端點
    (`https://app-api.pixverseai.cn/openapi/v2`)，再將 `region` 和
    `baseUrl` 寫入提供者設定。
  </Step>

  <Step title="將 PixVerse 設為預設影片提供者">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw config set agents.defaults.videoGenerationModel.primary "pixverse/v6"
    ```
  </Step>

  <Step title="生成影片">
    要求代理生成影片。PixVerse 會自動被使用。
  </Step>
</Steps>

## 支援的模式與模型

提供者會透過 OpenClaw 的共用影片工具公開 PixVerse 生成模型。

| 模式    | 模型            | 參考輸入       |
| ----- | ------------- | ---------- |
| 文字轉影片 | `v6`（預設）、`c1` | 無          |
| 圖片轉影片 | `v6`（預設）、`c1` | 1 張本機或遠端圖片 |

本機圖片參考會先上傳到 PixVerse，再發出圖片轉影片請求。遠端圖片 URL 會透過 PixVerse 圖片上傳端點以 `image_url` 傳遞。

| 選項   | 支援的值                                                              |
| ---- | ----------------------------------------------------------------- |
| 時長   | 1-15 秒                                                            |
| 解析度  | `360P`, `540P`, `720P`, `1080P`                                   |
| 長寬比  | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `2:3`, `3:2`, `21:9`，用於文字轉影片 |
| 生成音訊 | `audio: true`                                                     |

<Note>
  PixVerse 圖片範本生成尚未透過 `image_generate` 公開。該 API 由範本 ID 驅動，而 OpenClaw 的共用圖片生成合約目前沒有 PixVerse 專屬的型別化選項包。
</Note>

## 提供者選項

影片提供者接受以下選用的提供者專屬鍵：

| 選項                                   | 型別     | 效果                    |
| ------------------------------------ | ------ | --------------------- |
| `seed`                               | number | 支援時使用的確定性種子           |
| `negativePrompt` / `negative_prompt` | string | 負面提示詞                 |
| `quality`                            | string | PixVerse 畫質，例如 `720p` |
| `motionMode` / `motion_mode`         | string | 圖片轉影片動作模式             |
| `cameraMovement` / `camera_movement` | string | PixVerse 鏡頭運動預設       |
| `templateId` / `template_id`         | number | 已啟用的 PixVerse 範本 ID   |

## 設定

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "pixverse/v6",
      },
    },
  },
}
```

## 進階設定

<AccordionGroup>
  <Accordion title="API 區域">
    OpenClaw 預設使用國際 PixVerse API。當你的金鑰屬於特定 PixVerse 平台區域時，請手動設定 `models.providers.pixverse.region`，或使用
    `openclaw onboard --auth-choice pixverse-api-key` 在設定精靈中選擇：

    | 區域值             | PixVerse API 基底 URL                        |
    | --------------- | ------------------------------------------ |
    | `international` | `https://app-api.pixverse.ai/openapi/v2`   |
    | `cn`            | `https://app-api.pixverseai.cn/openapi/v2` |

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      models: {
        providers: {
          pixverse: {
            region: "cn", // "international" or "cn"
            baseUrl: "https://app-api.pixverseai.cn/openapi/v2",
            models: [],
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="自訂基底 URL">
    只有在透過可信任的相容代理路由時，才設定 `models.providers.pixverse.baseUrl`。
    `baseUrl` 的優先順序高於 `region`。

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      models: {
        providers: {
          pixverse: {
            baseUrl: "https://app-api.pixverse.ai/openapi/v2",
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="任務輪詢">
    PixVerse 會從生成請求回傳 `video_id`。OpenClaw 會輪詢
    `/openapi/v2/video/result/{video_id}`，直到任務成功、失敗或逾時。
  </Accordion>
</AccordionGroup>

## 相關

<CardGroup cols={2}>
  <Card title="影片生成" href="/zh-TW/tools/video-generation" icon="video">
    共用工具參數、提供者選擇與非同步行為。
  </Card>

  <Card title="設定參考" href="/zh-TW/gateway/config-agents#agent-defaults" icon="gear">
    代理預設設定，包括影片生成模型。
  </Card>
</CardGroup>