# ARK SDK 兼容

如果你之前已经用官方 Volcengine Ark SDK 接入了 seedance 视频生成，可以**只改两行配置**把流量切到 XRToken：

1. **base URL**：`https://ark.cn-beijing.volces.com/api/v3` → `https://api.xrtoken.net/api/v3`。`/v1`、`/v3`、`/api/v1` 同样可用。
2. **API Key**：把原本的 ARK_API_KEY 换成 XRToken 的 `tr-` 开头密钥

请求体、响应体、轮询 URL 拼接方式全部和官方一致。官方 SDK 默认带 `/api/v3` 前缀，host 换成我们即可，不必改成 `/v1`。

## 兼容范围

| 官方 ARK 路径 | XRToken 兼容地址 | 是否 SDK 直接可用 |
|---|---|---|
| `POST /contents/generations/tasks` | `POST /api/v3/contents/generations/tasks`（`/v1` `/v3` `/api/v1` 同路径） | ✅ |
| `GET /contents/generations/tasks/{id}` | `GET /api/v3/contents/generations/tasks/{id}`（同上） | ✅ |
| `DELETE /contents/generations/tasks/{id}` | `DELETE /api/v3/contents/generations/tasks/{id}`（同上） | ✅ |

ARK 路径返回的 `id` 字段直接是上游 seedance 任务 ID（与官方一致），后续轮询 / 取消用同一个 id 即可。

## Python SDK 示例

```python
from volcengine.maas.v3 import MaasService, Tasks

# 改成 XRToken 的 base URL + API key，其他不动（保留官方 /api/v3）
client = MaasService("https://api.xrtoken.net/api/v3", "cn-beijing")
client.set_ak_sk("", "")  # 不需要，下面改用 Bearer
client.set_token("tr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")

resp = client.create_task({
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "一只猫咪在草地上奔跑"}
  ],
})
print(resp["id"])
```

## 素材库：官方 Open API 格式兼容

素材库走官方 Open API（`POST /?Action=...`），原本需要 AK/SK 做 SigV4 签名。现在素材组 / 素材的创建、查询、列表、更新、删除，以及真人核验，都走官方 `POST /?Action=...` 路径：把 base URL 指向我们、把签名换成 Bearer 即可，请求 / 响应与官方一致。

### 兼容范围

| 官方 Action | XRToken 兼容地址 | 鉴权 | 说明 |
|---|---|---|---|
| `Action=CreateAssetGroup` | `POST /?Action=CreateAssetGroup&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=CreateAsset` | `POST /?Action=CreateAsset&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=GetAssetGroup` | `POST /?Action=GetAssetGroup&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=GetAsset` | `POST /?Action=GetAsset&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=ListAssetGroups` | `POST /?Action=ListAssetGroups&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=ListAssets` | `POST /?Action=ListAssets&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=UpdateAssetGroup` | `POST /?Action=UpdateAssetGroup&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=UpdateAsset` | `POST /?Action=UpdateAsset&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=DeleteAssetGroup` | `POST /?Action=DeleteAssetGroup&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=DeleteAsset` | `POST /?Action=DeleteAsset&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=CreateVisualValidateSession` | `POST /?Action=CreateVisualValidateSession&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |
| `Action=GetVisualValidateResult` | `POST /?Action=GetVisualValidateResult&Version=2024-01-01` | Bearer | 请求 / 响应与官方一致 |

鉴权方式：

- `Authorization: Bearer tr-xxx`（推荐）
- 或 `x-api-key: tr-xxx`

示例（创建素材组）：

```bash
curl -X POST "https://api.xrtoken.net/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "我的素材组",
    "ProjectName": "default"
  }'
```

示例（创建素材）：

```bash
curl -X POST "https://api.xrtoken.net/?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId": "group-2026**********-*****",
    "URL": "https://example.com/image.jpg",
    "Name": "test",
    "AssetType": "Image",
    "ProjectName": "default"
  }'
```

`ProjectName` 非必填：不传时自动使用网关项目（当前 `xrtoken`）；显式传值（包括 `default`）则原样透传，尊重你指定的项目。`CreateAsset` 的 `Name` 可选。查询素材组 / 素材：

```bash
curl -X POST "https://api.xrtoken.net/?Action=GetAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "Id": "group-2026**********-*****" }'
```

```bash
curl -X POST "https://api.xrtoken.net/?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "Id": "asset-20260423183015-xk4m2" }'
```

列表、删除、真人核验同样走 `POST /?Action=...`：

```bash
curl -X POST "https://api.xrtoken.net/?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": { "GroupIds": ["group-2026**********-*****"] },
    "PageNumber": 1,
    "PageSize": 10
  }'
```

```bash
curl -X POST "https://api.xrtoken.net/?Action=DeleteAsset&Version=2024-01-01" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "Id": "asset-20260423183015-xk4m2" }'
```

```bash
curl -X POST "https://api.xrtoken.net/?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer $XRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

响应与官方一致（`ResponseMetadata` / `Result` 信封），且沿用素材库的账号隔离：只能操作自己名下的分组和素材。

把签名调用换成 `Authorization: Bearer tr-xxx` 即可，请求 / 响应 body 一字不改。