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

# Upload and Manage Media Assets for Video Generation

> Upload, track, and manage media assets (images, videos, audio) used as references in Seedance 2.0 and SD2 Manxue video generation tasks.

Some video generation models — specifically **Seedance 2.0** and **SD2 Manxue** — support rich multi-modal reference inputs: you can supply reference images, videos, and audio clips to guide the output. However, when your reference media contains faces or virtual avatars, you must first upload those assets to the GlobalAI OPC asset library and wait for them to pass a content review before you can use them in a generation task. This page explains the full upload, review, and usage workflow for both models.

## When Do You Need Asset Management?

<Note>
  You only need to go through the asset management workflow in the following situations. For other reference inputs (standard images without faces, publicly accessible URLs), you can pass the URL directly in your generation request.
</Note>

* **When your reference images contain faces or virtual avatars** — these require platform moderation before use and must be uploaded via the asset API.
* **When you want to reuse the same reference media across multiple generation tasks** — uploading once and referencing by `assetId` is more efficient than passing a URL repeatedly.
* **When you want to explicitly manage, audit, or delete uploaded reference media** from your account's asset library.

## Seedance 2.0 Asset Workflow

<Steps>
  <Step title="Upload the asset">
    Send a `POST` request to `/kyyReactApiServer/kyyVideo2/asset/upload` with the following body parameters:

    | Parameter   | Type   | Required | Description                                                                            |
    | ----------- | ------ | -------- | -------------------------------------------------------------------------------------- |
    | `assetType` | string | Yes      | Asset type — `Image`, `Video`, `Audio`, or `Document` (first letter must be uppercase) |
    | `url`       | string | Yes      | Publicly accessible URL of the media file                                              |
    | `name`      | string | No       | A human-readable label for the asset                                                   |

    The API responds with an `assetId` in the format `asset-{timestamp}-{random}`.

    ```bash theme={null}
    curl -X POST https://zcbservice.aizfw.cn/kyyReactApiServer/kyyVideo2/asset/upload \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"assetType": "Image", "url": "https://example.com/portrait.jpg", "name": "My portrait"}'
    ```

    ```json theme={null}
    {
      "code": 0,
      "msg": null,
      "data": {
        "assetId": "asset-20260330142158-q75m8"
      }
    }
    ```
  </Step>

  <Step title="Poll for Active status">
    Send a `GET` request to `/kyyReactApiServer/kyyVideo2/asset/{assetId}` and check the `status` field in the response. Assets involving faces or virtual avatars are subject to a moderation review that may take additional time. Continue polling until the status is `Active`.

    ```bash theme={null}
    curl -X GET https://zcbservice.aizfw.cn/kyyReactApiServer/kyyVideo2/asset/asset-20260330142158-q75m8 \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "code": 0,
      "msg": null,
      "data": {
        "assetId": "asset-20260330142158-q75m8",
        "name": "My portrait",
        "assetType": "Image",
        "status": "Active",
        "url": "https://example.com/portrait.jpg",
        "createTime": "2026-03-30 14:21:58"
      }
    }
    ```
  </Step>

  <Step title="Reference the asset in a generation task">
    Once the asset status is `Active`, reference it in your Seedance 2.0 generation request using the `asset://{assetId}` URI format. Use the appropriate parameter depending on the asset type:

    * `first_image` or `last_image` — for an image that anchors the first or last frame of the video
    * `referenceImages` — for one or more style or subject reference images
    * `referenceVideos` — for a video reference clip
    * `referenceAudios` — for an audio reference track

    For example: `"first_image": "asset://asset-20260330142158-q75m8"`
  </Step>

  <Step title="Delete the asset when done">
    When you no longer need the asset, send a `DELETE` request to `/kyyReactApiServer/kyyVideo2/asset/{assetId}` to remove it from your library.

    ```bash theme={null}
    curl -X DELETE https://zcbservice.aizfw.cn/kyyReactApiServer/kyyVideo2/asset/asset-20260330142158-q75m8 \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "code": "0",
      "msg": "success",
      "data": null
    }
    ```
  </Step>
</Steps>

## SD2 Manxue Asset Workflow

SD2 Manxue uses a batch submission model — you can submit multiple image, video, and audio URLs in a single request. Each submitted asset receives its own `assetId` for individual tracking.

<Steps>
  <Step title="Submit assets for review">
    Send a `POST` request to `/kyyReactApiServer/asset/sd2Manxue/assetUpload` with arrays of URLs grouped by media type. You must include at least one non-empty array.

    | Parameter   | Type  | Description                                                                              |
    | ----------- | ----- | ---------------------------------------------------------------------------------------- |
    | `imageUrls` | array | List of image URLs to submit (recommended: aspect ratio 0.4–2.5, dimensions 300–6000 px) |
    | `videoUrls` | array | List of video URLs to submit                                                             |
    | `audioUrls` | array | List of audio URLs to submit                                                             |

    The response includes an `items` array where each entry contains its own `assetId` and an initial `status` of `submitted`.

    ```bash theme={null}
    curl -X POST https://zcbservice.aizfw.cn/kyyReactApiServer/asset/sd2Manxue/assetUpload \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "imageUrls": ["https://example.com/portrait.jpg"],
        "videoUrls": ["https://example.com/reference.mp4"],
        "audioUrls": ["https://example.com/bgm.mp3"]
      }'
    ```

    ```json theme={null}
    {
      "code": "0",
      "msg": null,
      "data": {
        "items": [
          {
            "assetType": "Image",
            "originalUrl": "https://example.com/portrait.jpg",
            "assetId": "asset_img_001",
            "status": "submitted"
          },
          {
            "assetType": "Video",
            "originalUrl": "https://example.com/reference.mp4",
            "assetId": "asset_video_001",
            "status": "submitted"
          }
        ],
        "failedItems": []
      }
    }
    ```
  </Step>

  <Step title="Poll for Active status">
    Send a `POST` request to `/kyyReactApiServer/asset/sd2Manxue/assetStatus` with the `assetIds` array containing the IDs you want to check. Poll this endpoint until every asset you need reports a status of `Active`.

    ```bash theme={null}
    curl -X POST https://zcbservice.aizfw.cn/kyyReactApiServer/asset/sd2Manxue/assetStatus \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "assetIds": ["asset_img_001", "asset_video_001"]
      }'
    ```

    ```json theme={null}
    {
      "code": "0",
      "msg": null,
      "data": {
        "items": [
          { "assetId": "asset_img_001", "status": "Active" },
          { "assetId": "asset_video_001", "status": "Processing" }
        ],
        "failedItems": []
      }
    }
    ```
  </Step>

  <Step title="Reference the assets in a generation task">
    Once all required assets are `Active`, reference them using the `asset://{assetId}` URI format in your SD2 Manxue generation request parameters (for example, `referenceImages`, `referenceVideos`, or `referenceAudios`).
  </Step>
</Steps>

## Asset Status Values

The following status values apply to both Seedance 2.0 and SD2 Manxue assets:

| Status                     | Meaning                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `submitted` / `Processing` | The asset has been received and is being reviewed or processed. Continue polling.         |
| `Active`                   | The asset has passed review and is ready to use in generation tasks.                      |
| `Failed`                   | The upload or content review failed. Check the error message and resubmit if appropriate. |

<Warning>
  **Deleted assets cannot be recovered.** Before deleting an asset, confirm it is not referenced by any active or pending generation tasks. Once deleted, the `assetId` is permanently invalidated and cannot be reused.
</Warning>

<Tip>
  Always check that your assets have status `Active` **before** submitting a generation task that references them. Submitting a generation task with a `Processing` or `Failed` asset will cause the task to fail. Build a short polling loop into your asset preparation step to avoid wasted generation calls.
</Tip>