# 同步素材状态 (/docs/user/materials/api/sync)



# 同步素材状态 [#同步素材状态]

## 同步素材状态 [#同步素材状态-1]

<Endpoint method="POST" path="/api/v1/materials/sync" />

### 认证方式 [#认证方式]

`Authorization: Bearer <API_KEY>`。

### 请求体 · application/json [#请求体--applicationjson]

无需字段，可传空对象 `{}`。

### 请求示例 [#请求示例]

```bash
curl -X POST "$LOCOPAL_BASE_URL/api/v1/materials/sync" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### 响应参数 [#响应参数]

| 参数                    | 类型      | 说明               |
| --------------------- | ------- | ---------------- |
| `code`                | integer | 成功时为 `0`         |
| `msg`                 | string  | 成功时为 `素材状态已同步`   |
| `data.groups`         | integer | 本次刷新到的分组数量       |
| `data.adopted_groups` | integer | 本次确认归属到当前账号的分组数量 |
| `data.assets`         | integer | 本次刷新到的素材数量       |
| `data.removed_assets` | integer | 确认已失效并被移除的素材数量   |

### 响应体 [#响应体]

```json
{
  "code": 0,
  "data": {
    "groups": 2,
    "adopted_groups": 0,
    "assets": 3,
    "removed_assets": 0
  },
  "msg": "素材状态已同步"
}
```

同步会按当前账号自己的分组逐个读取素材，刷新名称、状态、错误信息和素材地址。同步不会因为某一次查询没有返回记录就删除素材，只有再次单独查询确认确实不存在时才会移除，因此重复执行同步是安全的。

### 错误响应 [#错误响应]

| HTTP          | msg             | 说明                |
| ------------- | --------------- | ----------------- |
| `401`         | `Invalid token` | API Key 缺失、错误或已失效 |
| `502` / `503` | `素材服务暂不可用`      | 素材服务异常，保留请求信息后重试  |