> ## Documentation Index > Fetch the complete documentation index at: https://docs.wengaocloud.com/llms.txt > Use this file to discover all available pages before exploring further. # 创建素材 > 提交公网 HTTPS 素材 URL，或直接以 `multipart/form-data` 上传本地文件。平台将素材保存到平台存储并开始处理，返回平台素材 ID（`asset_xxx`）。 公开素材上传接口不需要传入 `model` 或模型 ID，平台内部按当前视频素材供应商配置完成路由。 素材处理完成（`status=active`）后才可用于视频生成，传入格式为 `asset://asset_xxx`。 提交公网 HTTPS 素材 URL，或直接以 `multipart/form-data` 上传本地文件。平台会将素材保存到平台存储并开始处理，返回平台素材 ID（`asset_xxx`）。 ``` POST /v1/assets Authorization: Bearer ``` 创建素材为**异步接口**，受理后返回 `status=processing`。需要轮询 `GET /v1/assets/{id}` 等待 `status=active` 后，才可在视频生成中使用该素材。 公开接口不需要传入 `model` 或模型 ID。素材上传会由平台内部按当前视频素材供应商配置完成路由。 视频生成请求中使用 `uri` 字段的值（即 `asset://asset_xxx`），不要使用 `id` 字段。传入时必须保留 `asset://` 前缀。 *** ## 请求参数 ### JSON URL 上传 ``` POST /v1/assets Authorization: Bearer Content-Type: application/json ``` | 参数 | 类型 | 必填 | 说明 | | ------------ | ------ | ----- | ------------------------------------- | | `asset_type` | string | **是** | 素材类型：`image`、`video`、`audio`。 | | `source_url` | string | **是** | 公网可访问的 HTTPS URL，平台下载校验并保存。 | | `name` | string | 否 | 素材名称，仅允许中文、字母、数字、下划线和短横线；未传时平台使用默认名称。 | ### 文件上传 ``` POST /v1/assets Authorization: Bearer Content-Type: multipart/form-data ``` | 参数 | 类型 | 必填 | 说明 | | ------------ | ------ | ----- | ------------------------------------- | | `file` | file | **是** | 要上传的图片、视频或音频文件。 | | `asset_type` | string | **是** | 素材类型：`image`、`video`、`audio`。 | | `name` | string | 否 | 素材名称，仅允许中文、字母、数字、下划线和短横线；未传时平台使用默认名称。 | 创建素材为异步接口，系统处理完成后素材状态变为 `active`。需轮询 `GET /v1/assets/{id}` 等待 `status=active` 后，才可在视频生成请求中使用。 视频生成时使用 `uri` 字段的值（即 `asset://asset_xxx`），不要使用 `id` 字段。传入时必须保留 `asset://` 前缀。 *** ## 素材格式要求 | 类型 | 格式 | 大小限制 | | -- | -------------------------------------- | --------------------------------------- | | 图片 | `jpeg`、`png`、`webp`、`bmp`、`tiff`、`gif` | 小于 30 MB；宽高比 (0.4, 2.5)；分辨率 300–6000 px | | 视频 | `mp4`、`mov` | 小于 50 MB；建议 2–15 秒 | | 音频 | `wav`、`mp3` | 小于 15 MB；建议 2–15 秒 | *** ## 示例 ### JSON URL 上传 ```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" }' ``` ### 文件上传 ```bash theme={null} curl -X POST "https://{your-domain}/v1/assets" \ -H "Authorization: Bearer $API_KEY" \ -F "asset_type=image" \ -F "name=avatar-reference" \ -F "file=@./avatar-reference.png" ``` **响应（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 } ``` *** ## 响应字段 | 字段 | 类型 | 说明 | | ------------ | ------- | --------------------------------------------- | | `id` | string | 平台素材 ID，格式 `asset_xxx`。 | | `uri` | string | 素材 URI，格式 `asset://asset_xxx`。**视频生成时使用此字段**。 | | `object` | string | 固定为 `asset`。 | | `asset_type` | string | 素材类型：`image`、`video`、`audio`。 | | `name` | string | 素材名称。 | | `status` | string | 素材状态，见下方状态说明。 | | `created_at` | integer | 创建时间，Unix 秒。 | | `updated_at` | integer | 最后更新时间，Unix 秒。 | *** ## 素材状态 | 状态 | 说明 | 可用于视频生成 | 下一步操作 | | ------------ | -------------- | ------- | ---------- | | `processing` | 平台已受理，正在保存或处理。 | 否 | 继续轮询 | | `active` | 素材可用。 | **是** | 可以在视频生成中使用 | | `failed` | 素材处理失败。 | 否 | 重新上传 | | `disabled` | 素材已被平台禁用。 | 否 | 联系平台 | *** ## 错误码 | HTTP 状态码 | `error.type` | 场景 | | -------- | --------------------------- | ------------------------------------------ | | 400 | `invalid_asset_type` | `asset_type` 不是 `image`、`video` 或 `audio`。 | | 400 | `invalid_asset_name` | `name` 包含不支持的字符。 | | 400 | `invalid_asset_url` | `source_url` 非 HTTPS、公网不可访问、格式不合法。 | | 400 | `invalid_multipart_request` | `multipart/form-data` 请求解析失败。 | | 400 | `invalid_asset_file` | 上传文件格式、大小、尺寸、时长等不符合素材要求。 | | 503 | `asset_store_unavailable` | 平台素材存储未配置。 | ## OpenAPI ````yaml POST /v1/assets openapi: 3.1.0 info: title: WengaoCloud AI Gateway API version: 0.1.0 description: WengaoCloud AI 聚合平台公开 API 契约草案，覆盖 OpenAI 兼容接口、Anthropic 原生接口和平台扩展接口。 servers: - url: https://xxx.wengaocloud.com description: 问高云 API 网关根域名。OpenAI SDK 的 base_url 使用 https://xxx.wengaocloud.com/v1。 - url: https://{tenant}.wengaocloud.com description: 控制台展示的租户或 OEM API 网关根域名。 variables: tenant: default: xxx security: - bearerAuth: [] tags: - name: models x-group: 模型 - name: openai-compatible x-group: OpenAI 兼容接口 - name: anthropic-native x-group: Anthropic 原生接口 - name: images-v3 x-group: 图片（V3 同步） - name: volcengine-images x-group: 图片（火山直连） - name: images x-group: 图片（V1 兼容） - name: async-images x-group: 图片异步任务 - name: aliwan-images x-group: 图片（百炼万相） - name: videos x-group: 视频 paths: /v1/assets: post: tags: - videos summary: 创建素材 description: > 提交公网 HTTPS 素材 URL，或直接以 `multipart/form-data` 上传本地文件。平台将素材保存到平台存储并开始处理，返回平台素材 ID（`asset_xxx`）。 公开素材上传接口不需要传入 `model` 或模型 ID，平台内部按当前视频素材供应商配置完成路由。 素材处理完成（`status=active`）后才可用于视频生成，传入格式为 `asset://asset_xxx`。 operationId: createAsset requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssetCreateRequest' examples: imageUrl: value: name: avatar-reference asset_type: image source_url: https://example.com/avatar-reference.png multipart/form-data: schema: $ref: '#/components/schemas/AssetUploadRequest' examples: imageFile: value: name: avatar-reference asset_type: image file: ./avatar-reference.png responses: '202': description: 素材已受理，正在处理中。 content: application/json: schema: $ref: '#/components/schemas/AssetResponse' examples: processing: value: id: asset_6f9a4c2b8d1e3a90 uri: asset://asset_6f9a4c2b8d1e3a90 object: asset asset_type: image name: avatar-reference status: processing created_at: 1779782400 updated_at: 1779782400 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: AssetCreateRequest: type: object required: - asset_type - source_url properties: name: type: string description: 素材名称。只能包含中文、字母、数字、下划线和短横线。 asset_type: type: string enum: - image - video - audio description: 素材类型。 source_url: type: string description: 公网可访问 HTTPS URL，平台会下载校验并保存。 AssetUploadRequest: type: object required: - asset_type - file properties: name: type: string description: 素材名称。只能包含中文、字母、数字、下划线和短横线。 asset_type: type: string enum: - image - video - audio description: 素材类型。 file: type: string format: binary description: 要上传的图片、视频或音频文件。 AssetResponse: type: object properties: id: type: string description: 平台素材 ID，格式 `asset_xxx`。 example: asset_6f9a4c2b8d1e3a90 uri: type: string description: 素材 URI，格式 `asset://asset_xxx`，视频生成请求中使用此值。 example: asset://asset_6f9a4c2b8d1e3a90 object: type: string enum: - asset asset_type: type: string enum: - image - video - audio name: type: string status: type: string enum: - processing - active - failed - disabled description: | 素材状态：`processing`（处理中，不可用于生成）、`active`（可用）、 `failed`（处理失败）、`disabled`（已禁用）。 resource_url: type: string format: uri description: >- 平台保存后的素材访问地址，通常为平台 CDN 地址；仅在列表接口传入 `include_resource_url=1` 且素材类型为图片或视频时返回。 created_at: type: integer updated_at: type: integer ErrorResponse: type: object properties: error: type: object properties: type: type: string example: invalid_request_error code: type: string example: model_endpoint_mismatch message: type: string example: 该模型不支持当前 endpoint。 responses: BadRequest: description: 请求参数无效。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: API Key 缺失或无效。 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key x-default: sk-your-api-key ````