# 登记素材

`POST /v1/assets`

需要 service.use 权限。从公开 HTTPS 地址登记图片、音频或视频，接受后异步获取并校验。幂等范围为团队与登记操作；相同请求重放原响应，不同请求拒绝。不支持素材输入的模型返回 invalid_request，且不创建素材、接入任务或额度预留。

- 在请求头 `Authorization: Bearer` 后面放 API 密钥；API 密钥需要 `service.use` 权限。
- 必须带 `Idempotency-Key`；相同请求重放原响应，不同请求被拒绝。
- 接受后异步获取并校验，按 `Location` 查询状态。
- 只有 `active` 素材可以在生成请求里用 `asset://` 引用。

## 请求头

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `Authorization` | string | 必填 | Bearer 加一个空格和 API 密钥。缺失或无效时返回 401 authentication_failed。 |
| `Content-Type` | string | 必填 | 请求体是 JSON：application/json。 |
| `X-Request-ID` | string | 可选 | 你自己的请求标识。无效或重复的值会被替换，最终值在响应头 X-Request-ID 返回。 |
| `Idempotency-Key` | string | 必填 | 每个新请求生成一个新值并保存，以字母或数字开头。结果不明时用同一个键和原请求体重试，会返回原响应；同一个键配不同的请求体返回 409 idempotency_conflict。键按团队区分，不按 API 密钥区分。 长度：8–128。 字符：A–Z a–z 0–9 . _ : -。 |

## 请求体 · application/json · 必填

请求体只接受下列字段，其他字段会被拒绝。

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `url` | string | 必填 | 公开 HTTPS 素材来源地址，UTF-8 编码最多 2048 字节，不得含用户信息；获取策略也拒绝不安全目的地。 长度：9–2048。 格式：https://。 |
| `media_type` | string | 必填 | 媒体类型。 `image`：图片； `audio`：音频； `video`：视频； |
| `model` | string | 必填 | 本次使用的模型标识。 `dreamina-seedance-2-0-260128`：Seedance 2.0； `dreamina-seedance-2-0-fast-260128`：Seedance 2.0 Fast； `dreamina-seedance-2-0-mini-260615`：Seedance 2.0 Mini； |
| `name` | string | 可选 | 可选显示名称；不含控制符、行段分隔符或双向文本控制符。 长度：1–64。 |

## 返回 · HTTP 202

素材接入已接受，请按 Location 查询状态。

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `asset_id` | string | 必填 | 平台素材标识。 长度：36–36。 格式：ast- 加 32 位十六进制。 |
| `status` | string | 必填 | 当前状态，具体含义见对应取值。 固定为：processing。 |

### 响应头

| 字段 | 类型 | 要求 | 说明 |
| --- | --- | --- | --- |
| `X-Request-ID` | string | 必填 | 本次请求的标识：你提供的有效值，或替换后的值。 |
| `Cache-Control` | string | 必填 | 响应不应被缓存。 |
| `Location` | string | 必填 | 已接受对象的规范查询路径。 |

## 状态码

每个 `error.code` 的处理办法见「[错误码](./api-docs-zh-api-errors.md)」。

| 状态码 | 说明 | error.code |
| --- | --- | --- |
| 202 | 素材接入已接受，请按 Location 查询状态。 响应头：`Cache-Control`, `Location` |  |
| 400 | 请求无效，或素材来源地址不符合 HTTPS 获取策略。 | invalid_request, source_url_not_allowed |
| 401 | API 密钥缺失或无效。 响应头：`WWW-Authenticate` | authentication_failed |
| 403 | 当前 API Key 缺少 service.use 权限。 | permission_denied |
| 409 | 本团队该操作键已用于不同的规范素材登记请求。 | idempotency_conflict |
| 410 | 原接受操作的精确重放响应已过期，不会再次创建。 | idempotency_replay_expired |
| 429 | 团队存储字节额度或素材接入容量不允许接受此素材。 | asset_intake_rate_limit_exceeded, asset_storage_quota_exceeded |
| 503 | 服务暂时不可用。 | dependency_unavailable |

## 相关指南

- [上传素材](./api-docs-zh-assets.md)
- [幂等与重试](./api-docs-zh-idempotency.md)

## 请求示例

```bash
IDEMPOTENCY_KEY=${IDEMPOTENCY_KEY:-$(uuidgen)}
printf '%s\n' "保存 IDEMPOTENCY_KEY，重试时原样复用：${IDEMPOTENCY_KEY}" >&2
curl --request POST "${CHENVOYA_BASE_URL}/v1/assets" \
  --header "Authorization: Bearer ${CHENVOYA_API_KEY}" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://images.example.test/reference.png",
  "media_type": "image",
  "model": "dreamina-seedance-2-0-260128",
  "name": "reference"
}'
```

```python
import urllib.request
import urllib.parse
import json
import os
import sys
import re
import uuid

key = os.environ["CHENVOYA_API_KEY"].strip()
if not key or re.search(r"[\x00-\x1f\x7f-\x9f]", key):
    sys.exit("Set CHENVOYA_API_KEY to a non-empty value without control characters")
base = os.environ["CHENVOYA_BASE_URL"].rstrip("/")
headers = {"Authorization": "Bearer " + key}
idempotency = os.environ.get("IDEMPOTENCY_KEY") or str(uuid.uuid4())
print("保存 IDEMPOTENCY_KEY，重试时原样复用：" + idempotency, file=sys.stderr)
headers["Idempotency-Key"] = idempotency
path = "/v1/assets"
body_text = "{\"url\":\"https://images.example.test/reference.png\",\"media_type\":\"image\",\"model\":\"dreamina-seedance-2-0-260128\",\"name\":\"reference\"}"
headers["Content-Type"] = "application/json"
body = json.dumps(json.loads(body_text)).encode("utf-8")
request = urllib.request.Request(base + path, data=body, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request) as response:
        print(response.read().decode("utf-8"))
except urllib.request.HTTPError as error:
    print(error.read().decode("utf-8"))
    sys.exit(1)
```

```javascript
// 需要 Node.js 20 及以上版本，保存为 .mjs 文件后运行。
const key = process.env.CHENVOYA_API_KEY?.trim();
if (!key || /[\x00-\x1f\x7f-\x9f]/.test(key)) {
  console.error("Set CHENVOYA_API_KEY to a non-empty value without control characters");
  process.exit(1);
}
const base = process.env.CHENVOYA_BASE_URL;
if (!base) throw new Error("Set CHENVOYA_BASE_URL");
const headers = {Authorization: `Bearer ${key}`};
const idempotency = process.env.IDEMPOTENCY_KEY || crypto.randomUUID();
console.error("保存 IDEMPOTENCY_KEY，重试时原样复用：" + idempotency);
headers["Idempotency-Key"] = idempotency;
const path = "/v1/assets";
let bodyText = "{\"url\":\"https://images.example.test/reference.png\",\"media_type\":\"image\",\"model\":\"dreamina-seedance-2-0-260128\",\"name\":\"reference\"}";
headers["Content-Type"] = "application/json";
const body = JSON.stringify(JSON.parse(bodyText));
const response = await fetch(base.replace(/\/$/, "") + path, {method: "POST", headers, body: body});
console.log(await response.text());
if (!response.ok) process.exitCode = 1;
```

```go
package main

import (
	"crypto/rand"
	"fmt"
	"io"
	"net/http"
	"os"
	"regexp"
	"strings"
)

func main() {
	key := strings.TrimSpace(os.Getenv("CHENVOYA_API_KEY"))
	if key == "" || regexp.MustCompile(`[\x00-\x1f\x7f-\x9f]`).MatchString(key) {
		fail("Set CHENVOYA_API_KEY to a non-empty value without control characters")
	}
	base := strings.TrimRight(os.Getenv("CHENVOYA_BASE_URL"), "/")
	if base == "" {
		fail("Set CHENVOYA_BASE_URL")
	}
	path := "/v1/assets"
	bodyText := "{\"url\":\"https://images.example.test/reference.png\",\"media_type\":\"image\",\"model\":\"dreamina-seedance-2-0-260128\",\"name\":\"reference\"}"
	request, err := http.NewRequest("POST", base+path, strings.NewReader(bodyText))
	if err != nil {
		fail(err.Error())
	}
	request.Header.Set("Authorization", "Bearer "+key)
	request.Header.Set("Content-Type", "application/json")
	idempotency := os.Getenv("IDEMPOTENCY_KEY")
	if idempotency == "" {
		idempotency = newOperationKey()
	}
	fmt.Fprintln(os.Stderr, "保存 IDEMPOTENCY_KEY，重试时原样复用："+idempotency)
	request.Header.Set("Idempotency-Key", idempotency)
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		fail(err.Error())
	}
	text, err := io.ReadAll(response.Body)
	response.Body.Close()
	if err != nil {
		fail(err.Error())
	}
	fmt.Println(string(text))
	if response.StatusCode < 200 || response.StatusCode > 299 {
		os.Exit(1)
	}
}

func fail(message string) {
	fmt.Fprintln(os.Stderr, message)
	os.Exit(1)
}

// newOperationKey returns a random UUID; save it to retry with the same value.
func newOperationKey() string {
	var b [16]byte
	if _, err := rand.Read(b[:]); err != nil {
		fail(err.Error())
	}
	b[6] = b[6]&0x0f | 0x40
	b[8] = b[8]&0x3f | 0x80
	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
}
```

## 响应示例

202

```json
{
  "asset_id": "ast-11111111111111111111111111111111",
  "status": "processing"
}
```

400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "invalid asset request"
  },
  "trace_id": "trace_asset_invalid"
}
```

401

```json
{
  "error": {
    "code": "authentication_failed",
    "message": "authentication failed"
  },
  "trace_id": "trace_error_example"
}
```

403

```json
{
  "error": {
    "code": "permission_denied",
    "message": "permission denied"
  },
  "trace_id": "trace_asset_permission"
}
```

409

```json
{
  "error": {
    "code": "idempotency_conflict",
    "message": "idempotency key conflicts with the original request"
  },
  "trace_id": "trace_asset_conflict"
}
```

410

```json
{
  "error": {
    "code": "idempotency_replay_expired",
    "message": "asset create replay expired"
  },
  "trace_id": "trace_asset_expired"
}
```

429

```json
{
  "error": {
    "code": "asset_storage_quota_exceeded",
    "message": "asset storage quota exceeded"
  },
  "trace_id": "trace_asset_quota"
}
```

503

```json
{
  "error": {
    "code": "dependency_unavailable",
    "message": "service is not ready"
  },
  "trace_id": "trace_error_example"
}
```