API 接口文档：上传图片到图床

1. 接口概述

本接口用于将本地图片文件上传至系统的图床服务器，上传成功后通常会返回该图片的在线访问链接。

• 当前状态: ?? 开发中 (Developing)

2. 接口详情

• 请求方式: POST
• 请求路径: https://api.codingplanx.ai/api/upload
• 数据格式: multipart/form-data

3. 请求参数

3.1 请求头 (Headers)

3.2 请求体 (Body)

本接口采用 multipart/form-data 格式传输数据，具体字段如下：

4. 响应参数

4.1 响应状态

• HTTP 状态码: 200 OK
• Content-Type: application/json

4.2 响应数据结构

当前接口响应模型暂未定义具体字段（Schema为空对象 {}），以下为通用成功响应示例：

{
  "code": 200,
  "message": "成功"
}

(注：实际开发完成后，通常会在此 JSON 对象中包含图片的 URL 地址，如 "url": "https://...")

---

5. 请求示例代码

为了方便您快速接入，以下提供三种常见语言/工具的调用示例：

5.1 cURL

curl --location --request POST 'https://api.codingplanx.ai/api/upload' \
--form 'file=@"/C:/Users/Administrator/Desktop/d63ea1bd9011777e653b1addc7a88433.png"'

5.2 Python (Requests)

import requests

url = "https://api.codingplanx.ai/api/upload"

payload={}
files=[
  ('file',('image.png',open('C:/Users/Administrator/Desktop/d63ea1bd9011777e653b1addc7a88433.png','rb'),'image/png'))
]
headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

5.3 JavaScript (Fetch API)

const myHeaders = new Headers();

const formdata = new FormData();
// 假设 fileInput 是您 HTML 中的 <input type="file"> 元素
formdata.append("file", fileInput.files[0], "d63ea1bd9011777e653b1addc7a88433.png");

const requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: formdata,
  redirect: 'follow'
};

fetch("https://api.codingplanx.ai/api/upload", requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

---

6. 常见问题解答 (FAQs)

Q1: 接口上传支持哪些图片格式？

A: 通常情况下，图床接口支持主流的图片格式，如 JPG, JPEG, PNG, GIF, 和 WebP。建议在请求时确保文件扩展名和 MIME 类型正确。具体限制请以后端实际校验规则为准。

Q2: 图片上传是否有文件大小限制？

A: 是的。虽然文档暂未标注，但为了保证服务器稳定性，通常会对上传文件进行大小限制（如单张图片不超过 5MB 或 10MB）。如果上传过大的文件，可能会收到 413 Payload Too Large 的 HTTP 状态码报错。

Q3: 为什么我在前端调用时遇到了 CORS (跨域) 错误？

A: 这是因为前端页面所在的域名与 API 域名 (api.codingplanx.ai) 不一致，触发了浏览器的同源策略限制。请联系后端开发人员在服务器端配置正确的 Access-Control-Allow-Origin 响应头，或者在前端本地开发时使用 Proxy 代理进行调试。

Q4: 文档中写着 file 参数是“非必填”的，如果不传会怎样？

A: 当前接口定义中 file 标记为 required: false。如果不传该参数，接口依然会返回 200 OK 状态码（基于当前设计），但无法真正完成图片存储业务。建议在业务逻辑中始终附带该文件参数。

Q5: 上传成功后，我如何获取图片的 URL？

A: 接口当前处于 developing（开发中）状态，返回的 JSON Schema 暂时为空。开发完成后，开发团队会在 200 响应体的 JSON 中增加返回字段（例如 url 或 data.link）。请关注本 API 文档的后续更新。