API 概览

## PaperBanana API 将 PaperBanana 的核心能力封装为 HTTP API，统一异步任务模式。 ### 典型流程 1. `POST /api/v1/generate` 提交任务 2. `GET /api/v1/tasks/{task_id}` 轮询状态 3. `GET /api/v1/tasks/{task_id}/image` 下载最终图片 ### 鉴权 除 `/health`、`/docs`、`/redoc`、`/openapi.json`、`/static/docs.html` 外， 所有接口都需要 `Authorization: Bearer `。

服务地址
https://api2.paperbanana.me
端点数量
9
生成时间
2026-02-26 15:18:20

调用流程：提交任务 -> 轮询状态 -> 下载结果。任务均为异步执行。

鉴权

除心跳检测与文档接口外，业务接口都需要 Bearer Token。

Authorization: Bearer <API_TOKEN>
GET 心跳检测

/health

用于检测服务是否存活。

心跳检测
响应
状态码说明
200请求成功
请求命令（cURL） 
curl -X GET "https://api2.paperbanana.me/health"
POST 提交生成任务 需鉴权

/api/v1/generate

提交单个生成任务，返回 task_id 后异步执行。

生成接口
请求类型（Content-Type）

application/json

参数说明
参数位置类型必填说明
source_context body string 是 源文本上下文
communicative_intent body string 是 图表标题 / 传达意图
task_name body enum(diagram, plot) 否 任务类型（diagram / plot）
exp_mode body enum(vanilla, dev_planner, dev_planner_stylist, dev_planner_critic, demo_planner_critic, dev_full, demo_full, dev_polish, dev_retriever) 否 流水线模式
retrieval_setting body enum(auto, manual, random, none) 否 检索策略
max_critic_rounds body integer 否 Critic 最大轮数
aspect_ratio body string 否 输出宽高比
model_name body string 否 覆盖默认文本模型
image_model_name body string 否 覆盖默认图片模型
do_eval body boolean 否 是否执行评估
raw_data body object 否 plot 任务原始 JSON 数据
path_to_gt_image body string 否 dev_polish 模式参考图路径
metadata body object 否 业务透传字段
响应
状态码说明
202请求成功
422参数校验错误
请求命令（cURL） 
curl -X POST "https://api2.paperbanana.me/api/v1/generate" -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{}'
POST 批量提交任务 需鉴权

/api/v1/generate/batch

批量提交多个生成任务，返回 batch_id 与 task_ids。

批量接口
请求类型（Content-Type）

application/json

参数说明
参数位置类型必填说明
items body array[object] 是 批量任务列表
max_concurrent body integer 否 批量并发上限
响应
状态码说明
202请求成功
422参数校验错误
请求命令（cURL） 
curl -X POST "https://api2.paperbanana.me/api/v1/generate/batch" -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{}'
GET 查询批次状态 需鉴权

/api/v1/batches/{batch_id}

查询批次内任务的 pending/running/completed/failed 统计。

批量接口
参数说明
参数位置类型必填说明
batch_id path string 是 批次 ID
响应
状态码说明
200请求成功
422参数校验错误
请求命令（cURL） 
curl -X GET "https://api2.paperbanana.me/api/v1/batches/{batch_id}" -H "Authorization: Bearer "
POST 提交精修任务 需鉴权

/api/v1/refine

提交图片精修任务，返回 refine task_id 后异步执行。

精修接口
请求类型（Content-Type）

application/json

参数说明
参数位置类型必填说明
image_base64 body string 否 待精修图片 base64
image_url body string 否 待精修图片 URL
edit_prompt body string 是 精修指令
aspect_ratio body string 否 输出宽高比
image_size body enum(1K, 2K, 4K, 1k, 2k, 4k) 否 输出分辨率（1K/2K/4K）
image_model_name body string 否 覆盖默认图片模型
output_format body enum(png, jpg, jpeg) 否 输出格式（png/jpg/jpeg）
响应
状态码说明
202请求成功
422参数校验错误
请求命令（cURL） 
curl -X POST "https://api2.paperbanana.me/api/v1/refine" -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{}'
GET 查询生成任务 需鉴权

/api/v1/tasks/{task_id}

轮询生成任务状态，直到 completed 或 failed。

任务接口
参数说明
参数位置类型必填说明
task_id path string 是 任务 ID
响应
状态码说明
200请求成功
422参数校验错误
请求命令（cURL） 
curl -X GET "https://api2.paperbanana.me/api/v1/tasks/{task_id}" -H "Authorization: Bearer "
GET 下载生成结果 需鉴权

/api/v1/tasks/{task_id}/image

下载生成任务最终图片文件。

任务接口
参数说明
参数位置类型必填说明
task_id path string 是 任务 ID
响应
状态码说明
200请求成功
422参数校验错误
请求命令（cURL） 
curl -X GET "https://api2.paperbanana.me/api/v1/tasks/{task_id}/image" -H "Authorization: Bearer "
GET 查询精修任务 需鉴权

/api/v1/refine/{task_id}

轮询精修任务状态，直到 completed 或 failed。

精修接口
参数说明
参数位置类型必填说明
task_id path string 是 任务 ID
响应
状态码说明
200请求成功
422参数校验错误
请求命令（cURL） 
curl -X GET "https://api2.paperbanana.me/api/v1/refine/{task_id}" -H "Authorization: Bearer "
GET 下载精修结果 需鉴权

/api/v1/refine/{task_id}/image

下载精修任务最终图片文件。

精修接口
参数说明
参数位置类型必填说明
task_id path string 是 任务 ID
响应
状态码说明
200请求成功
422参数校验错误
请求命令（cURL） 
curl -X GET "https://api2.paperbanana.me/api/v1/refine/{task_id}/image" -H "Authorization: Bearer "