小描开发者 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": 105
}

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 · JOURNAL FIGURES

提交研究内容，领取期刊图 PNG

期刊图使用独立任务接口和处理队列，不影响原有路径识别。基础设计：仅文字，10 个额度；高级设计：文字＋参考图，45 个额度。提交成功立即扣费，之后失败、取消或过期均不退还；下载不重复扣费。成品完成后保留48小时，请及时下载。

POST/api/journal-figure-jobs提交扣 10 或 45 个额度

提交期刊图任务

brief 提交研究内容，可选附加最多 6 个 JPG、PNG 或 PDF 参考文件。

GET/api/journal-figure-jobs/{job_id}不扣费

查询期刊图状态

返回 received、processing、completed、cancelled、expired 或 failed。

GET/api/journal-figure-jobs/{job_id}/result不重复扣费

下载期刊图 PNG

只返回 PNG，宽高和比例不限；提交时已经计费，下载不再扣费。

DELETE/api/journal-figure-jobs/{job_id}不退还已扣额度

取消未完成任务

取消 received 或 processing 任务；提交时已扣额度不退还。

cURL文字 + 可选参考文件

curl -X POST "https://xiaomiao-ai.com/api/journal-figure-jobs" \
  -H "Authorization: Bearer $XIAOMIAO_API_KEY" \
  -F "brief=绘制肿瘤细胞与成纤维细胞相互作用机制图" \
  -F "references=@reference.png" \
  -F "references=@paper.pdf"

JSON201 Created

{
  "ok": true,
  "job_id": "jfig_6a4e...",
  "status": "received",
  "reserved_credits": 3,
  "credits_left": 102,
  "status_url": "https://xiaomiao-ai.com/api/journal-figure-jobs/jfig_6a4e...",
  "result_url": "https://xiaomiao-ai.com/api/journal-figure-jobs/jfig_6a4e.../result",
  "billing": "twenty_credits_reserved_first_result_download"
}

brief 必填，长度为 1–12000 字。
references 可重复，支持 JPG、PNG、PDF；最多 6 个。
单个参考文件不超过 10 MB，合计不超过 30 MB。
成品只返回有效 PNG，不限制宽高和画面比例。

05 · 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"))

06 · BILLING

两项功能共享余额，分别计费

0 次上传图片

0 次排队与处理

0 次查询状态

1 次首次下载结果

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

10 个基础设计：仅文字

45 个高级设计：文字＋参考图

不退还提交成功即扣费

0 个查询和下载

基础设计：仅文字，10 个额度；高级设计：文字＋参考图，45 个额度。提交成功立即扣费，之后失败、取消或过期均不退还；下载不重复扣费。成品完成后保留48小时，请及时下载。新任务结果响应头 x-xiaomiao-charged: 0，表示下载时不再扣费。更新前任务保留原计费规则。

07 · RETENTION

路径数据保留15分钟；期刊图成品保留48小时

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

08 · ERRORS

HTTP 错误码

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

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

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

409结果仍在处理中

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

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

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

500服务暂时无法完成请求

小描开发者文档