> ## 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 동영상 생성을 위한 공식 외부 Plugin으로 `pixverse`를 제공합니다. 이 Plugin은 `videoGenerationProviders` 계약에 `pixverse` 공급자를 등록합니다.

| 속성         | 값                                                |
| ---------- | ------------------------------------------------ |
| 공급자 ID     | `pixverse`                                       |
| Plugin 패키지 | `@openclaw/pixverse-provider`                    |
| 인증 환경 변수   | `PIXVERSE_API_KEY`                               |
| 온보딩 플래그    | `--auth-choice pixverse-api-key`                 |
| 직접 CLI 플래그 | `--pixverse-api-key <key>`                       |
| API        | PixVerse Platform API v2 (`video_id` 제출 및 결과 폴링) |
| 기본 모델      | `pixverse/v6`                                    |
| 기본 API 리전  | 국제                                               |

## 시작하기

<Steps>
  <Step title="Plugin 설치">
    ```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
    ```

    마법사는 공급자 구성에 `region`과 `baseUrl`을 쓰기 전에 국제 엔드포인트
    (`https://app-api.pixverse.ai/openapi/v2`)를 사용할지, CN 엔드포인트
    (`https://app-api.pixverseai.cn/openapi/v2`)를 사용할지 묻습니다.
  </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 | `720p` 같은 PixVerse 품질 |
| `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="/ko/tools/video-generation" icon="video">
    공유 도구 매개변수, 공급자 선택, 비동기 동작입니다.
  </Card>

  <Card title="구성 참조" href="/ko/gateway/config-agents#agent-defaults" icon="gear">
    동영상 생성 모델을 포함한 에이전트 기본 설정입니다.
  </Card>
</CardGroup>