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

# Create asset

Upload a public HTTPS asset URL. The platform downloads, validates, and stores it in the asset library, then returns the asset ID and `uri`.

```
POST /v1/assets
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

Asset creation is asynchronous. The initial response usually has `status=processing`. Poll [Query asset](/en/api/videos/get-asset) until it becomes `status=active`, then use it in video generation.

<Note>
  In video generation requests, use the `uri` value, such as `asset://asset_xxx`. Do not pass the raw `id`. Keep the `asset://` prefix.
</Note>

## Request parameters

| Parameter    | Type   | Required | Description                                                                |
| ------------ | ------ | -------- | -------------------------------------------------------------------------- |
| `asset_type` | string | Yes      | Asset type: `image`, `video`, or `audio`.                                  |
| `source_url` | string | Yes      | Publicly reachable HTTPS URL. The platform downloads and stores the asset. |
| `name`       | string | No       | Asset name for display only. Defaults to a generated name.                 |

## Format requirements

| Type  | Formats                                     | Size limit                              |
| ----- | ------------------------------------------- | --------------------------------------- |
| Image | `jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif` | Under 30 MB; recommended 300 to 4000 px |
| Video | `mp4`, `mov`                                | Under 50 MB; recommended 2 to 5 seconds |
| Audio | `wav`, `mp3`                                | Under 15 MB; recommended 2 to 5 seconds |

## Example

```bash theme={null}
curl -X POST "https://{your-domain}/v1/assets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "avatar-reference",
    "asset_type": "image",
    "source_url": "https://example.com/avatar-reference.png"
  }'
```

## Success response

HTTP status: `202 Accepted`

```json theme={null}
{
  "id": "asset_6f9a4c2b8d1e3a90",
  "uri": "asset://asset_6f9a4c2b8d1e3a90",
  "object": "asset",
  "asset_type": "image",
  "name": "avatar-reference",
  "status": "processing",
  "created_at": 1779782400,
  "updated_at": 1779782400
}
```

## Response fields

| Field        | Type    | Description                                                                |
| ------------ | ------- | -------------------------------------------------------------------------- |
| `id`         | string  | Platform asset ID, formatted as `asset_xxx`.                               |
| `uri`        | string  | Asset URI, formatted as `asset://asset_xxx`. Use this in video generation. |
| `object`     | string  | Always `asset`.                                                            |
| `asset_type` | string  | Asset type.                                                                |
| `name`       | string  | Asset name.                                                                |
| `status`     | string  | Asset status, see below.                                                   |
| `created_at` | integer | Creation time in Unix seconds.                                             |
| `updated_at` | integer | Last update time in Unix seconds.                                          |

## Asset statuses

| Status       | Description                                                          | Usable in video generation | Next step                          |
| ------------ | -------------------------------------------------------------------- | -------------------------- | ---------------------------------- |
| `processing` | The platform has accepted the asset and is storing or processing it. | No                         | Keep polling                       |
| `active`     | The asset is ready.                                                  | Yes                        | You can use it in video generation |
| `failed`     | Asset processing failed.                                             | No                         | Upload again                       |
| `disabled`   | Asset was disabled by the platform.                                  | No                         | Contact the platform               |

## Error codes

| HTTP status | `error.type`              | Scenario                                                             |
| ----------- | ------------------------- | -------------------------------------------------------------------- |
| 400         | `invalid_asset_type`      | `asset_type` is not `image`, `video`, or `audio`.                    |
| 400         | `invalid_asset_name`      | `name` contains unsupported characters.                              |
| 400         | `invalid_asset_url`       | `source_url` is not HTTPS, is not publicly reachable, or is invalid. |
| 503         | `asset_store_unavailable` | Asset storage is not configured.                                     |