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

# 从图片创建角色

> 从图片创建可复用角色，并可选提取 3D vsplat。

异步创建可复用的角色素材。请轮询角色，直到 `status` 为 `ready` 后再将其 ID 用于渲染。

`type` 决定输出：`render`（默认）仅创建可用于渲染的 2D 角色，`vsplat` 仅创建 3D 高斯泼溅模型，`all` 同时创建两者并分别计费。vsplat 提取就绪后，通过[导出 3D 角色](/zh/v1/api-reference/characters/export)获取下载链接。

<Note>
  **计费**（1 积分 = \$0.01）：`type=render` 固定 1 积分；`type=vsplat` 固定 25 积分，设置 `enhance=true` 时为 30 积分。增强仅影响 vsplat 提取，30 积分替代原有 25 积分，并非额外叠加。`type=all` 合计为 26 积分，增强时为 31 积分。详见[计费与保留期限](/zh/v1/pricing)。
</Note>

## 请求参数

使用 `multipart/form-data`。

| 参数          | 类型      |  必填 | 默认值      | 说明                                                                                       |
| ----------- | ------- | :-: | -------- | ---------------------------------------------------------------------------------------- |
| `image`     | file    | 二选一 | —        | 直接上传的角色源图片，支持 PNG、JPEG、WebP。与 `image_url` 二选一。                                           |
| `image_url` | string  | 二选一 | —        | 可公开访问的图片 HTTP(S) URL。替代 `image`，并在开始接收素材时保持可访问。                                          |
| `name`      | string  |  否  | `""`     | 详情和列表中显示的名称，便于识别角色，不影响生成。                                                                |
| `type`      | string  |  否  | `render` | `render` 创建 2D 角色（1 积分），`vsplat` 创建 3D 模型（25 积分，增强时 30），`all` 同时创建（26 或 31 积分）。          |
| `enhance`   | boolean |  否  | `false`  | 是否对 vsplat 提取执行额外的 AI 增强。仅 `vsplat`/`all` 生效；`render` 下不生效、不收费。将 vsplat 费用由 25 改为 30 积分。 |

`image` 与 `image_url` 必须二选一。以下参数仅适用于 `type=vsplat` 或 `all`。

| 参数                   | 类型      |  必填 | 默认值     | 说明                                                                        |
| -------------------- | ------- | :-: | ------- | ------------------------------------------------------------------------- |
| `model_precision`    | number  |  否  | —       | 模型提取精度，范围 `(0, 1]`。在编码之前的 PKL 提取阶段生效。                                     |
| `filter_low_quality` | boolean |  否  | `false` | 编码前剔除低重要性高斯点的总开关。为 `true` 时移除低于提取服务质量阈值的点。                                |
| `joint_set`          | string  |  否  | `body`  | vsplat 绑定的骨架：`full`、`expression` 或 `body`，不影响价格。                          |
| `render_thumbnail`   | boolean |  否  | `false` | 是否在提取时生成标准角色预览缩略图。渲染来源和姿势由服务内部选择。                                         |
| `task_id`            | string  |  否  | —       | `type=vsplat` 的调用者自定义幂等 ID。同一任务重试使用稳定且唯一的值；`type=all` 的配套提取使用新建角色 ID 作为键。 |

<Note>
  **`joint_set` 骨架：** `full` 保留全部 441 个关节，包含完整面部骨架，支持表情动画；`expression` 保留 119 个身体及表情关节；`body` 仅保留 86 个身体关节，移除全部面部关节，不能播放面部动画。减少关节只改变关节列表与蒙皮矩阵 `W` 的列，不改变高斯点数量；因此 `body` 仍保留完整面部细节，只是无法让面部运动。省略时，V1 会填入 `body`（提取服务内部默认虽为 `full`，但 V1 会先填入 `body`）。驱动该角色的动作应使用相同的 `joint_set`。

  这与动作导出的 `download_type=metahuman` 骨架兼容，关节一一对应，配合使用无需重定向。见[导出 3D 动作](/zh/v1/api-reference/motions/export)。`download_type=mixamo` 则是通用的 50 关节骨架，用于驱动自己的角色网格时仍需重定向。
</Note>

<Note>
  本页列出了完整的公开请求参数。工作流存储路径、输出 URI、多视图与蒙皮配置、缩略图渲染细节由服务选择或生成。
</Note>

## 响应参数

返回 `200 OK` 和 Character 对象。

| 字段             | 类型             | 始终返回 | 说明                                                                                                                  |
| -------------- | -------------- | :--: | ------------------------------------------------------------------------------------------------------------------- |
| `id`           | string         |   是  | 角色公开 ID，例如 `char_550e8400-e29b-41d4-a716-446655440000`，请原样保存。                                                       |
| `status`       | string         |   是  | 初始通常为 `queued`，终态为 `ready`/`failed`。`all` 必须等 2D 和 vsplat 都就绪才为 `ready`；任一失败则为 `failed`，可结合 `vsplat.status` 定位。     |
| `name`         | string         |   是  | 传入的名称，或空字符串。                                                                                                        |
| `progress`     | integer 或 null |   是  | 可用时为 0–100 的进度。                                                                                                     |
| `capabilities` | string\[]      |   是  | 就绪前为空；具备视频渲染能力的就绪角色包含 `video_render`。                                                                               |
| `created_at`   | string 或 null  |   是  | 带 UTC 偏移的 ISO 8601 时间，如 `2026-07-31T09:15:22+00:00`。                                                                |
| `completed_at` | string 或 null  |   是  | ISO 8601 完成时间，完成前为 `null`。                                                                                          |
| `error`        | object 或 null  |   是  | 失败时的结构化错误，否则为 `null`。                                                                                               |
| `type`         | string         |   是  | 请求中的 `render`、`vsplat` 或 `all`。                                                                                     |
| `vsplat`       | object 或 null  |   是  | 仅 `render` 时为 `null`；否则为 `{status, error}`，表示提取自身的状态。无下载链接，下载请调用[导出 3D 角色](/zh/v1/api-reference/characters/export)。 |
| `glb`          | null           |   是  | 角色始终为 `null`。                                                                                                       |

```json theme={null}
{
  "id": "char_550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "name": "Presenter",
  "progress": 0,
  "capabilities": [],
  "created_at": "2026-07-31T09:15:22+00:00",
  "completed_at": null,
  "error": null,
  "type": "render",
  "vsplat": null,
  "glb": null
}
```

## 示例

<CodeGroup>
  ```go Go theme={null}
  body := &bytes.Buffer{}
  writer := multipart.NewWriter(body)
  part, _ := writer.CreateFormFile("image", "character.png")
  file, _ := os.Open("character.png")
  defer file.Close()
  io.Copy(part, file)
  writer.WriteField("name", "Presenter")
  writer.Close()

  req, _ := http.NewRequest("POST", "https://apis.viggle.ai/v1/characters", body)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY"))
  req.Header.Set("Content-Type", writer.FormDataContentType())
  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()
  ```

  ```javascript JavaScript theme={null}
  const form = new FormData();
  form.append("image", imageFile);
  form.append("name", "Presenter");

  const response = await fetch("https://apis.viggle.ai/v1/characters", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
    body: form,
  });
  const character = await response.json();
  ```

  ```python Python theme={null}
  import os
  import requests

  with open("character.png", "rb") as image:
      response = requests.post(
          "https://apis.viggle.ai/v1/characters",
          headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
          files={"image": image},
          data={"name": "Presenter"},
      )
  response.raise_for_status()
  character = response.json()
  ```

  ```bash cURL theme={null}
  curl -X POST "https://apis.viggle.ai/v1/characters" \
    -H "Authorization: Bearer $VIGGLE_API_KEY" \
    -F "image=@character.png" \
    -F "name=Presenter"
  ```
</CodeGroup>

提取 3D vsplat 时添加 `-F "type=vsplat"`；若同时保留渲染能力，使用 `all`：

```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image=@character.png" \
  -F "type=all" \
  -F "model_precision=0.8" \
  -F "render_thumbnail=true"
```

AI 增强需在 `type=vsplat` 或 `type=all` 下添加 `-F "enhance=true"`。单独使用 `enhance` 不生效；vsplat 费用变为固定 30 积分，而非 25：

```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image=@character.png" \
  -F "type=vsplat" \
  -F "enhance=true"
```

`joint_set` 默认为 `body`。保留表情关节时添加 `-F "joint_set=expression"`，保留全部 441 个关节时使用 `full`。驱动动作也应使用相同的 `joint_set`：

```bash cURL theme={null}
curl -X POST "https://apis.viggle.ai/v1/characters" \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -F "image=@character.png" \
  -F "type=vsplat" \
  -F "joint_set=expression"
```

## 下一步

使用[获取角色](/zh/v1/api-reference/characters/get)轮询返回的 ID，等待就绪。若请求了 vsplat，再通过[导出 3D 角色](/zh/v1/api-reference/characters/export)下载。


## OpenAPI

````yaml zh/openapi.yaml POST /v1/characters
openapi: 3.0.3
info:
  title: Viggle API
  description: 使用 AI 生成角色动画视频。
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: 生产服务器
security:
  - bearerAuth: []
tags:
  - name: Renders
    description: 准备输入、创建渲染、观察进度并获取结果。
  - name: Credits
    description: 查询当前调用者可用的积分余额。
  - name: Characters
    description: 创建、列出、查询和删除可复用角色。type 决定是否同时提取 3D vsplat，就绪后通过导出接口获取下载链接。
  - name: Motions
    description: 创建、列出、查询和删除可复用动作，也可从官方模板导入。type 决定是否提取或生成 3D 动画，就绪后通过导出接口获取下载链接。
  - name: Videos
    description: 生成 MiniMax H3 视频（vid_）或角色动画视频（anim_），并统一查询调用者的 H3、角色动画及角色动作渲染（render_）结果。
paths:
  /v1/characters:
    parameters:
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/SourceChannel'
    post:
      tags:
        - Characters
      summary: 从图片创建角色
      description: 从图片创建可复用角色，并可选提取 3D vsplat。
      operationId: v1CreateCharacter
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateCharacterForm'
      responses:
        '200':
          description: 请求成功。
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          $ref: '#/components/responses/ResourceBadRequest'
        '401':
          $ref: '#/components/responses/ResourceUnauthorized'
        '402':
          $ref: '#/components/responses/ResourcePaymentRequired'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/ResourceConflict'
        '500':
          $ref: '#/components/responses/ResourceInternalServerError'
        '502':
          $ref: '#/components/responses/ResourceBadGateway'
        '503':
          $ref: '#/components/responses/ResourceServiceUnavailable'
components:
  parameters:
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      description: 可选的调用者自定义关联 ID，最长 128 字符。服务会在响应头返回实际使用的值，便于追踪和支持排查。
      schema:
        type: string
        minLength: 1
        maxLength: 128
    SourceChannel:
      name: X-Viggle-Source
      in: header
      required: false
      description: 可选来源标签，最长 128 字符，用于识别 SDK、集成、产品入口或内部工作流。
      schema:
        type: string
        minLength: 1
        maxLength: 128
  schemas:
    CreateCharacterForm:
      description: >-
        image 与 image_url 必须二选一。type 选择输出，详见创建角色。其后的提取参数仅适用于 vsplat 或
        all。工作流路径、输出 URI、多视图、缩略图相机及姿势、渲染来源和静止模式均由服务管理。
      type: object
      properties:
        image:
          type: string
          format: binary
          description: 直接上传的角色源图片，支持 PNG、JPEG、WebP。与 `image_url` 二选一。
        image_url:
          type: string
          format: uri
          description: 可公开访问的图片 HTTP(S) URL。替代 `image`，并在开始接收素材时保持可访问。
        name:
          type: string
          description: 详情和列表中显示的名称，便于识别角色，不影响生成。
          default: ''
        type:
          type: string
          description: >-
            `render` 创建 2D 角色（1 积分），`vsplat` 创建 3D 模型（25 积分，增强时 30），`all`
            同时创建（26 或 31 积分）。
          enum:
            - render
            - vsplat
            - all
          default: render
        enhance:
          description: >-
            是否对 vsplat 提取执行额外的 AI 增强。仅 `vsplat`/`all` 生效；`render` 下不生效、不收费。将
            vsplat 费用由 25 改为 30 积分。
          type: boolean
          default: false
        joint_set:
          type: string
          enum:
            - expression
            - body
            - full
          default: body
          description: vsplat 绑定的骨架：`full`、`expression` 或 `body`，不影响价格。
        model_precision:
          type: number
          description: 模型提取精度，范围 `(0, 1]`。在编码之前的 PKL 提取阶段生效。
          minimum: 0
          exclusiveMinimum: true
          maximum: 1
        filter_low_quality:
          description: 编码前剔除低重要性高斯点的总开关。为 `true` 时移除低于提取服务质量阈值的点。
          type: boolean
          default: false
        render_thumbnail:
          description: 是否在提取时生成标准角色预览缩略图。渲染来源和姿势由服务内部选择。
          type: boolean
          default: false
        task_id:
          description: >-
            `type=vsplat` 的调用者自定义幂等 ID。同一任务重试使用稳定且唯一的值；`type=all` 的配套提取使用新建角色 ID
            作为键。
          type: string
          minLength: 1
    Asset:
      description: >-
        角色和动作共用的资源结构。列表中的 progress 为 null，顶层 error 当前始终为 null，失败请检查 status。角色
        type 为 render、vsplat、all，动作为 render、glb、all，旧资源默认报告 render。vsplat/glb
        仅包含提取状态，下载链接通过角色或动作的 /export 获取。未请求提取时对应字段为 null。all 需等 2D 与 3D 均就绪才为
        ready；任一失败则顶层 failed，子对象状态可用于定位。
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - name
        - progress
        - capabilities
        - created_at
        - completed_at
        - error
        - type
        - vsplat
        - glb
      properties:
        id:
          type: string
          description: 素材公开 ID。角色通常以 char_ 开头，动作通常以 mot_ 开头。
          minLength: 1
        status:
          description: 素材整体生命周期。所需能力就绪后才能用于渲染或导出。
          allOf:
            - $ref: '#/components/schemas/ResourceStatus'
        name:
          type: string
          description: 创建时提供或导入时生成的显示名称；不支持名称的流程可能返回空字符串。
        progress:
          type: integer
          description: 详情中尽可能提供 0–100 的处理百分比，列表中或不可用时为 null。
          nullable: true
          minimum: 0
          maximum: 100
        capabilities:
          description: 素材具备的能力。就绪且可渲染时包含 video_render。
          type: array
          items:
            type: string
        created_at:
          description: 带 UTC 偏移的 ISO 8601 时间，例如 2026-07-31T09:15:22+00:00。
          type: string
          nullable: true
        completed_at:
          type: string
          description: 所有请求处理进入终态时的 ISO 8601 时间，带 UTC 偏移；处理中为 null。
          nullable: true
        error:
          type: object
          description: 保留的顶层错误详情，目前始终为 null。通过 status 判断失败，并在适用时检查提取子对象。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ResourceError'
        type:
          type: string
          description: 创建时请求的输出。render 为可渲染的 2D 素材，vsplat/glb 为 3D 输出，all 同时请求两种支持的输出。
          enum:
            - render
            - vsplat
            - glb
            - all
          default: render
        vsplat:
          description: >-
            角色 vsplat 提取状态。动作及 type=render 的角色为 null。这里只返回状态，不回显 model_precision
            等创建参数。
          nullable: true
          type: object
          additionalProperties: false
          required:
            - status
            - error
          properties:
            status:
              description: 角色 vsplat 提取自身的生命周期，独立于顶层素材状态。
              allOf:
                - $ref: '#/components/schemas/ResourceStatus'
            error:
              type: object
              description: vsplat 状态为 failed 时的结构化错误，否则为 null。
              nullable: true
              allOf:
                - $ref: '#/components/schemas/ResourceError'
        glb:
          description: 动作 3D 动画提取或生成状态。角色及 type=render 的动作为 null。
          nullable: true
          type: object
          additionalProperties: false
          required:
            - status
            - skeletons
            - error
          properties:
            status:
              description: 动作 3D 提取或生成自身的生命周期，独立于顶层素材状态。
              allOf:
                - $ref: '#/components/schemas/ResourceStatus'
            skeletons:
              description: >-
                可通过 GET /v1/motions/{motion_id}/export?download_type=
                导出的骨架。就绪前为空；两种骨架预先一起生成，就绪后为 [mixamo, metahuman]。
              type: array
              items:
                type: string
                enum:
                  - mixamo
                  - metahuman
            error:
              type: object
              description: 3D 动画状态为 failed 时的结构化错误，否则为 null。
              nullable: true
              allOf:
                - $ref: '#/components/schemas/ResourceError'
    ResourceStatus:
      description: 异步资源共用的公开生命周期，枚举值与 RenderStatus 相同。
      type: string
      enum:
        - queued
        - processing
        - ready
        - failed
        - cancelled
    ResourceError:
      description: >-
        异步资源附带的错误。code 为稳定的小写下划线字符串，故意不限制为枚举，工作进程可能新增值；无公开映射时使用
        processing_failed。已发布值包括
        worker_stopped、motion_model_mismatch、image_required、motion_video_required、unsupported_video_format、video_too_long、video_too_large、video_resolution_too_high、video_unreadable、invalid_background_mode、video_dimensions_must_be_even、result_expired、video_inaccessible、no_humans_detected、all_workers_busy、task_failed、unexpected_error、processing_failed。
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          description: 稳定的小写下划线异步错误码。集合可扩展，客户端应容忍新值。
          minLength: 1
        message:
          type: string
          description: 供人阅读的异步处理失败说明。
        request_id:
          type: string
          description: 工作进程或原始请求的关联 ID，不可用时为 null。
          nullable: true
    ResourceErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          description: 同步资源操作失败的顶层错误对象。
          allOf:
            - $ref: '#/components/schemas/ResourceHttpError'
    ResourceHttpError:
      description: >-
        同步资源请求的错误封装。错误码由 API 服务中的固定映射生成，无公开映射的失败使用 processing_failed。资源的异步 error
        对象采用 ResourceError 中更广泛、可扩展的错误码集合。
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - request_id
      properties:
        code:
          type: string
          description: 同步资源请求的固定小写下划线错误码，用于程序化处理。
          enum:
            - authentication_required
            - invalid_api_key
            - insufficient_credits
            - invalid_request
            - motion_not_ready
            - character_not_found
            - motion_not_found
            - not_found
            - id_already_exists
            - rate_limited
            - service_unavailable
            - task_failed
            - internal_error
            - processing_failed
        message:
          type: string
          description: 供人阅读的同步请求失败说明。
        request_id:
          description: 同步失败时始终为 null，请通过 X-Request-Id 响应头关联请求。
          type: string
          nullable: true
  headers:
    RequestId:
      description: 用于支持排查和追踪的稳定请求 ID。
      schema:
        type: string
  responses:
    ResourceBadRequest:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceUnauthorized:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourcePaymentRequired:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceNotFound:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceConflict:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceInternalServerError:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceBadGateway:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
    ResourceServiceUnavailable:
      description: 请求失败，详情见错误响应。
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth access token
      description: 服务端 SDK 使用项目 API 密钥，Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

````