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

# 上传图片与临时 URL

> 图片格式、大小限制、有效期和后续使用方式

商品分析、A+ 策划和生图接口通过 URL 接收图片。没有公开 URL 的本地图片，需要先上传到灵感临时存储。

## 文件要求

| 项目    | 限制                     |
| ----- | ---------------------- |
| 表单字段  | `file`                 |
| 请求格式  | `multipart/form-data`  |
| 支持格式  | PNG、JPEG、WebP、GIF、AVIF |
| 单文件大小 | 1 字节至 30 MB            |
| 有效期   | 最长 3 天                 |

平台会根据文件内容识别真实格式，不只检查扩展名或浏览器提交的 MIME 类型。损坏、截断或格式不支持的文件会被拒绝。

```bash theme={null}
curl --request POST \
  --url 'https://api.ch88.cn/v1/open/uploads/images' \
  --header 'Authorization: Bearer <PUBLIC_API_KEY>' \
  --form 'file=@./product.png'
```

```json theme={null}
{
  "code": 201,
  "data": {
    "id": "generated/open-upload/550e8400-e29b-41d4-a716-446655440000.png",
    "url": "https://api.ch88.cn/v1/linggan/media/assets/generated%2Fopen-upload%2F550e8400-e29b-41d4-a716-446655440000.png",
    "expiresAt": "2026-09-15T08:30:00.000Z"
  },
  "request_id": "req_01K4Y8R6Z1J2X3M4N5P6Q7R8S9"
}
```

## 字段说明

| 字段               | 说明                                     |
| ---------------- | -------------------------------------- |
| `data.id`        | 临时存储对象标识，通常不需要自行使用。                    |
| `data.url`       | 可直接访问的完整图片地址，也可直接传入后续接口的 `image_urls`。 |
| `data.expiresAt` | 预计过期时间，ISO 8601 UTC 格式。                |

## 三天有效期如何计算

* 图片上传成功时开始计算，最长保留 72 小时。
* 到期后，存储生命周期规则会自动删除对应对象。
* 删除存在后台执行时间差；即使到期后短时间仍能访问，也不代表有效期延长。
* 过期或已清理的 URL 返回 `404`。
* 客户端应以 `expiresAt` 为准，并在到期前重新上传或永久保存。

<Warning>
  临时 URL 不是永久图床。请勿把它直接保存为电商平台的长期商品图片地址。
</Warning>

## 常见错误

| HTTP 状态 | 错误码                      | 处理方式             |
| ------- | ------------------------ | ---------------- |
| `400`   | `FILE_REQUIRED`          | 确认表单字段名为 `file`。 |
| `400`   | `INVALID_IMAGE_FILE`     | 重新导出完整的受支持图片。    |
| `413`   | `FILE_TOO_LARGE`         | 压缩到 30 MB 以下再上传。 |
| `503`   | `STORAGE_NOT_CONFIGURED` | 平台存储暂时不可用，稍后重试。  |