> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/api-reference/endpoints/kyc-asset-flow.md).

# Seedance 2.0 KYC Asset

## Seedance 2.0 KYC Flow

This flow is required only when you want to generate video from KYC-bound user identity inputs on Seedance 2.0 (portrait, user voice, or user-owned reference video).

No KYC asset is needed for plain text-to-video, or for normal non-KYC parts such as `imageUrl`, `videoUrl`, and `audioUrl`.

### End-to-End Flow

1. Create KYC asset by URL.
2. Poll asset until `active`.
3. Call video generation with KYC content parts.
4. Poll video task until terminal status.

### APIs Used

| Step | Method | Path                               | Purpose                                              |
| ---- | ------ | ---------------------------------- | ---------------------------------------------------- |
| 1    | `POST` | `/api/v1/kyc/user/assets`          | Create async KYC asset from HTTPS URL.               |
| 2    | `GET`  | `/api/v1/kyc/user/assets/:assetId` | Poll until `status` is `active` or `failed`.         |
| 3    | `POST` | `/api/v1/video/generations`        | Submit Seedance 2.0 generation with KYC asset parts. |
| 4    | `GET`  | `/api/v1/video/tasks/:taskId`      | Poll task to get final output.                       |

### KYC Asset Create Request

`POST /api/v1/kyc/user/assets`

| Field       | Type   | Required | Validation                                  | Description                              |
| ----------- | ------ | -------- | ------------------------------------------- | ---------------------------------------- |
| `url`       | string | Yes      | Must be a valid HTTPS URL                   | Public file URL for backend ingestion.   |
| `assetType` | string | No       | `Image`, `Video`, `Audio` (default `Image`) | KYC asset type.                          |
| `name`      | string | No       | Max length 64                               | Friendly name for search and management. |

Notes:

* Upload is URL-only for this endpoint.
* Asset starts as `processing` and must become `active` before generation usage.
* If the asset ends up `failed`, check `errorCode` / `errorMessage` on the asset for the reason.

### File Input Validation

The backend only validates `url` / `assetType` / `name` at the DTO layer when the asset is created. The actual file content is fetched and validated afterward, while the asset is `processing`. If the downloaded file fails content validation, the asset transitions to `failed` — check `errorCode` / `errorMessage` on the asset for the reason.

Clients should pre-check files against the limits below before calling this endpoint, to avoid burning an asset's lifecycle on a file that is guaranteed to fail once downloaded.

| Asset Type | Formats                                    | Aspect Ratio (W/H) | Edge Length (px) | Duration     | Total Pixels (W×H) | File Size | FPS       |
| ---------- | ------------------------------------------ | ------------------ | ---------------- | ------------ | ------------------ | --------- | --------- |
| Image      | jpeg, png, webp, bmp, tiff, gif, heic/heif | (0.4, 2.5)         | (300, 6000)      | —            | —                  | < 30 MB   | —         |
| Video      | mp4, mov                                   | \[0.4, 2.5]        | \[300, 6000]     | \[2, 15] sec | \[409600, 2086876] | ≤ 50 MB   | \[24, 60] |
| Audio      | wav, mp3                                   | —                  | —                | \[2, 15] sec | —                  | ≤ 15 MB   | —         |

Notes:

* Ranges shown as `(a, b)` are exclusive; `[a, b]` are inclusive, matching the backend's actual bounds.
* These limits apply to the downloaded file content, not the DTO request — a request can pass DTO validation (valid HTTPS `url`) and still end up `failed` if the fetched file violates any bound above.

### KYC Asset Status Lifecycle

| Status       | Meaning                                   | Action                                     |
| ------------ | ----------------------------------------- | ------------------------------------------ |
| `processing` | Asset is being validated and preprocessed | Continue polling                           |
| `active`     | Asset is ready for inference              | Use in video generation                    |
| `failed`     | Asset cannot be used                      | Show `errorMessage` and create a new asset |

### Using KYC Asset in Video Request

`POST /api/v1/video/generations`

Use `content` parts with `type` mapped to created KYC asset type:

| Content Part Type | Required Asset Type |
| ----------------- | ------------------- |
| `kycImageAssetId` | `Image`             |
| `kycVideoAssetId` | `Video`             |
| `kycAudioAssetId` | `Audio`             |

Example payload:

```json
{
  "model": "dreamina-seedance-2-0",
  "content": [
    { "type": "text", "text": "the person speaks naturally" },
    { "type": "kycImageAssetId", "assetId": "asset-...-image" },
    { "type": "kycAudioAssetId", "assetId": "asset-...-audio" }
  ],
  "duration": 5,
  "resolution": "720p"
}
```

### Validation and Failure Cases

* KYC parts are accepted only by Seedance 2.0 models (`dreamina-seedance-2-0`, `dreamina-seedance-2-0-fast`, `dreamina-seedance-2-0-mini`).
* Backend validates ownership and asset status before credit reservation.
* Common `400` cases:
  * Model is not Seedance 2.0 but request includes KYC parts.
  * Asset does not belong to current user.
  * Asset is not `active`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avis.xyz/api-reference/endpoints/kyc-asset-flow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.