小描开发者 API 文档

01 · QUICKSTART

快速开始

购买后会收到一个以 img_live_ 开头的 API Key。把它放入 Authorization 请求头，通过 multipart 表单上传图片。

cURL提交图片

curl -X POST "https://xiaomiao-ai.com/api/images" \
  -H "Authorization: Bearer $XIAOMIAO_API_KEY" \
  -F "image=@figure.png"

JSON201 Created

{
  "ok": true,
  "image_id": "img_8f31c2...",
  "status": "received",
  "expires_at": "2026-08-17T15:15:00.000Z",
  "result_url": "https://xiaomiao-ai.com/api/images/img_8f31c2...",
  "result_file_url": "https://xiaomiao-ai.com/api/images/img_8f31c2.../result",
  "billing": "first_result_download",
  "credits_left": 150
}

02 · AUTHENTICATION

API Key 鉴权

除健康检查外，所有客户接口都要求 Bearer 鉴权。API Key 只应保存在服务端环境变量中，不要写进前端网页、公开仓库或聊天记录。

请求头Authorization: Bearer img_live_你的_API_Key

03 · ENDPOINTS

接口列表

POST/api/images不扣费

提交图片

使用 multipart/form-data 的 image 字段上传 PNG、JPEG 或 WebP。

GET/api/images/{image_id}不扣费

查询任务状态

返回 processing、completed 或 expired，以及结果下载地址和过期时间。

GET/api/images/{image_id}/result首次扣 1 次

下载 SVG 结果

首次成功下载扣除 1 次额度；同一结果重复下载不再扣费。

GET/api/images/{image_id}/file不扣费

读取原始图片

仅在处理完成前可读取；结果生成后原始图片立即删除。

04 · COMPLETE EXAMPLE

上传、轮询并保存结果

下面的 Python 示例完成完整流程。状态查询不会扣费，只有第一次成功请求 result_file_url 时扣除 1 次。

Pythonrequests

import time
import requests

BASE = "https://xiaomiao-ai.com"
headers = {"Authorization": "Bearer img_live_替换为你的_API_Key"}

with open("figure.png", "rb") as image:
    response = requests.post(
        f"{BASE}/api/images",
        headers=headers,
        files={"image": ("figure.png", image, "image/png")},
        timeout=60,
    )
response.raise_for_status()
job = response.json()

while True:
    status = requests.get(job["result_url"], headers=headers, timeout=30)
    status.raise_for_status()
    if status.json()["status"] == "completed":
        break
    time.sleep(2)

result = requests.get(job["result_file_url"], headers=headers, timeout=60)
result.raise_for_status()
with open("result.svg", "wb") as output:
    output.write(result.content)

print("本次是否扣费：", result.headers.get("x-xiaomiao-charged"))

05 · BILLING

只在首次取回结果时计费

0 次上传图片

0 次排队与处理

0 次查询状态

1 次首次下载结果

结果响应头 x-xiaomiao-charged: 1 表示本次完成首次扣费；返回 0 表示该结果此前已经计费，本次没有重复扣除。

06 · RETENTION

数据只保留 15 分钟

未完成任务从提交时间起保留 15 分钟。
处理完成后，原始图片立即删除。
SVG 结果从完成时间起保留 15 分钟。
过期任务返回 HTTP 410，内容不可恢复。
API Key 的剩余额度和累计用量不随任务删除。

07 · ERRORS

HTTP 错误码

400请求格式或表单字段错误

401缺少、无效或已撤销的 API Key

402首次取回结果时额度不足

409结果仍在处理中

410任务已过期或内容已清理

413图片超过 10 MB 或 3200 万像素

415图片格式无效或不受支持

500服务暂时无法完成请求

小描开发者文档