> ## 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.

# 快速开始

> 完成图片上传、任务提交、状态查询和结果下载

下面用 cURL 完成一次最小商品图生成流程。把示例中的 `<PUBLIC_API_KEY>` 替换为你的完整成员级密钥。

## 1. 保存密钥

```bash theme={null}
export LINGGAN_API_KEY="<PUBLIC_API_KEY>"
```

密钥只应保存在服务端环境变量或密钥管理系统中，不要写入网页前端代码、Git 仓库或日志。

## 2. 上传商品图

```bash theme={null}
curl --request POST \
  --url 'https://api.ch88.cn/v1/open/uploads/images' \
  --header "Authorization: Bearer ${LINGGAN_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.url` 保存为 `IMAGE_URL`。该地址最长有效 3 天。

## 3. 提交商品图生成任务

```bash theme={null}
curl --request POST \
  --url 'https://api.ch88.cn/v1/open/product-images/generations' \
  --header "Authorization: Bearer ${LINGGAN_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "生成一张简洁高级的护肤品电商主图，产品居中，背景干净，保留真实包装细节。",
    "image_urls": [
      "<IMAGE_URL>"
    ],
    "product_info": {
      "name": "保湿精华液",
      "sellingPoints": "清爽肤感，适合日常保湿",
      "platform": "Amazon"
    },
    "size": "1:1",
    "resolution": "1k",
    "output_language": "zh-cn"
  }'
```

成功响应：

```json theme={null}
{
  "code": 200,
  "data": {
    "status": "submitted",
    "task_id": "task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9"
  },
  "request_id": "req_01K4Y8R6Z1J2X3M4N5P6Q7R8S9"
}
```

<Warning>
  生图提交响应不是最终图片。请读取 `data.task_id`，然后查询任务状态。
</Warning>

## 4. 查询任务

提交后先等待 5 秒：

```bash theme={null}
curl --request GET \
  --url 'https://api.ch88.cn/v1/open/tasks/task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9' \
  --header "Authorization: Bearer ${LINGGAN_API_KEY}"
```

任务成功时：

```json theme={null}
{
  "code": 200,
  "data": {
  "task_id": "task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9",
  "status": "succeeded",
  "created_at": "2026-09-12T08:30:00.000Z",
  "completed_at": "2026-09-12T08:31:42.000Z",
  "result": {
    "images": [
      {
        "asset_id": "generated/open-result/task_01K4Y8R6Z1J2X3M4N5P6Q7R8S9-0.png",
        "url": "https://api.ch88.cn/v1/open/assets/generated%2Fopen-result%2Ftask_01K4Y8R6Z1J2X3M4N5P6Q7R8S9-0.png",
        "expires_at": "2026-09-15T08:31:42.000Z"
      }
    ]
  },
  "error": null
  },
  "request_id": "req_01K4Y8R6Z1J2X3M4N5P6Q7R8S9"
}
```

## 5. 下载结果

`data.result.images[].url` 是可以直接访问的完整地址：

```bash theme={null}
curl --location \
  --url '<RESULT_IMAGE_URL>' \
  --output result.png
```

<Note>
  图片最长保留 3 天。浏览器缓存不能代替永久存储，请在有效期内下载到自己的对象存储或文件系统。
</Note>