run.py 接口教程 · 本机自用的生图 API

Step 0 · Setup

快速开始

三步进入状态：启动服务 → 验证在线 → 就可以开始调接口了。

STEP 1

启动服务

终端里运行 run.py，看到「🚀 启动中」即成功。终端窗口保持开着——关掉终端等于关掉服务。

终端

/Users/hao/miniconda3/envs/modelscope/bin/python \
  /Users/hao/DOC/py/2026/modelscope/run.py

STEP 2

验证在线

新开一个终端敲一条命令，返回 JSON 就说明接口活着。网页界面会自动打开，但接口不依赖它。

验证

curl http://127.0.0.1:7862/api/info

STEP 3

确认 Key 就绪

同目录的 ModelScope_Token.txt 里放好 API Key（一行一个，# 开头是注释）。没有 Key，生图接口会报「无可用的 API Key」。

💡

为什么是 127.0.0.1？这表示只监听本机回环地址：只有这台 Mac 上的程序能访问，局域网和公网都进不来，天然安全，所以不需要账号密码。

Main Flow

核心五步：从选模型到拿到图

生图是「提交任务 → 轮询状态 → 拿结果」的异步模式。下面五步照抄命令就能跑通。

1

确认服务在线

任何调用前先确认服务活着，避免后面白忙。

curl

curl http://127.0.0.1:7862/api/info

2

查模型库，拿 `model` 路径

每个模型有一个路径标识（如 bozoyan/k-yanbo），生图时必须带上。返回里的 prefix 触发词服务端会自动拼，不用管。

按分类 / 关键词查模型

# 只看 LORA 分类
curl "http://127.0.0.1:7862/api/models?category=LORA"

# 带关键词搜索
curl "http://127.0.0.1:7862/api/models?q=yanbo"

3

提交生图任务

提示词直接写中文就行——服务端会自动「联想扩写 → 翻译英文 → 拼触发词」。返回 task_ids，记下来。

POST /api/generate

curl -s -X POST http://127.0.0.1:7862/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bozoyan/k-yanbo",
    "prompt": "阳光下的少女，白色连衣裙，微风吹过",
    "count": 2,
    "size": "1080x1440",
    "steps": 8,
    "guidance": 1.0,
    "sampler": "Euler"
  }'

# 返回 → {"task_ids": ["a1b2...", "e5f6..."]}

4

轮询任务状态

一张图一般 10~30 秒，隔 3~5 秒查一次。status 变成 succeed 就完事了。

POST /api/tasks

curl -s -X POST http://127.0.0.1:7862/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"task_ids": ["a1b2c3d4..."]}'

status	含义
`pending`	排队中
`running`	生成中，message 字段有进度秒数
`succeed`	成功 → path 是本地文件，url 是线上地址
`failed`	失败 → error 字段看原因

5

拿到图

成功后有两个入口：本地文件直接能用；浏览器打开本地图片走 /api/image。

本地文件：path 字段，如 …/k-yanbo/0903193025_1-Euler-1.0-8.png，同时同目录 模型名.md 追加了提示词记录
线上地址：url 字段（ModelScope 临时图床，可直接下载）

Reference

/api/generate 参数详解

只有 model 和 prompt 必填，其余全部有默认值。带 image_urls 时进入图生图模式。

参数	必填	默认	说明
`model`	✱ 必填	—	模型路径，从 /api/models 的 model 字段取
`prompt`	✱ 必填	—	正向提示词，支持纯中文，自动扩写+翻译
`count`	可选	6	一次生成几张，范围 1~21
`size`	可选	1080x1440	宽x高，预设见下表
`steps`	可选	8	采样步数 1~60，不同底座建议值不同
`guidance`	可选	1.0	CFG 引导系数 1~10
`sampler`	可选	Euler	采样器，可选值见下表
`image_urls`	可选	—	参考图 URL 数组（≤4 张）。有此项 = 图生图，count 强制为 1

尺寸预设（size 可选值）

比例	值	比例	值	比例	值
1:1	`1240x1240`	9:16	`900x1600`	3:2	`1440x960`
3:4	`1080x1440`	16:9	`1600x900`	2:5	`720x1800`
4:3	`1440x1080`	1:2	`870x1740`	5:2	`1800x720`
2:3	`960x1440`	2:1	`1740x870`	3:5	`960x1600`
4:5	`1080x1350`	1:3	`720x2160`	5:3	`1600x960`
5:4	`1350x1080`	3:1	`2160x720`

采样器与底座参数建议

sampler 可选值
Euler · Euler a · DPM++ SDE DPM++ SDE Karras · DPM++ 2M SDE DPM++ 2M Karras · LCM DPM2 a · DDIM Normal

底座 Bmodel	CFG	steps
Krea-2-Turbo	1	8
Z-Image-Turbo	7.5	9
Z-Image	4	50
FLUX.2-klein-9B	1	4
FLUX.1-dev	3.5	30
SDXL / SD1.5	7.5	35
Qwen-Image / FLUX.2-dev	4	30

Prompt Tools

提示词工具（4 个）

统一格式：POST /api/tools/<名字>，请求体 {"text": "…"}。expand / keywords / analyze 返回 en+zh 双语；translate 返回 zh。

/api/tools/expand

扩展提示词

一句话主题 → 完整画面描述（细节 / 情感 / 风格），先英文后中文。

示例

curl -s -X POST http://127.0.0.1:7862/api/tools/expand \
  -H "Content-Type: application/json" \
  -d '{"text": "阳光下的少女"}'

/api/tools/keywords

关键字转换

主题 → 画质加权关键词（8k / masterpiece 等），适配 SD / MJ。

示例

curl -s -X POST http://127.0.0.1:7862/api/tools/keywords \
  -H "Content-Type: application/json" \
  -d '{"text": "赛博朋克城市夜景"}'

/api/tools/translate

英译中

英文 prompt 按中文语义习惯翻译。

示例

curl -s -X POST http://127.0.0.1:7862/api/tools/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "a girl in white dress"}'

/api/tools/analyze

图片解析（图生提示词）

text 传图片 URL，或本地图转 base64 dataURI（≤15MB）。

示例

curl -s -X POST http://127.0.0.1:7862/api/tools/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "https://…/xxx.jpg"}'

Cheat Sheet

全部接口速查

共 14 个接口。核心是 generate / tasks，其余按需取用。

接口	方法	作用
`/api/info`	GET	服务信息：分类、尺寸预设、采样器、Key 模式
`/api/models?category=&q=`	GET	查模型库，拿 model 路径
`/api/generate`	POST	提交生图任务（核心），返回 task_ids
`/api/task/<id>`	GET	查单个任务状态
`/api/tasks`	POST	批量查任务状态
`/api/tools/<name>`	POST	提示词工具 ×4（见上节）
`/api/repair`	POST	GPen 人像修复，返回 task_id
`/api/gallery?model=`	GET	某模型历史出图列表
`/api/image?path=`	GET	读取本地图片（仅限 run.py 目录内）
`/api/open-folder`	POST	Finder 打开出图文件夹
`/api/launch-depth`	POST	拉起 MiDaS 深度估计服务（7877）

⚠️

count 别拉满 21 张随手提交——那会同时开 21 个并发生图任务，API Key 池很快被打到限流。日常建议 ≤6 张。

Script

Python 调用示例

一段可以直接复制的完整脚本：查模型 → 提交 → 轮询 → 输出结果。保存为 .py 用 modelscope 环境运行即可。

api_demo.py

import time, requests

BASE = "http://127.0.0.1:7862"

# 1) 查模型
models = requests.get(f"{BASE}/api/models", params={"category": "LORA"}).json()
model_path = models["items"][0]["model"]

# 2) 提交生图（中文直接写）
r = requests.post(f"{BASE}/api/generate", json={
    "model": model_path,
    "prompt": "黄昏海滩上的灯塔，油画风格",
    "count": 2,
}).json()
task_ids = r["task_ids"]

# 3) 轮询直到全部完成
while True:
    tasks = requests.post(f"{BASE}/api/tasks", json={"task_ids": task_ids}).json()["tasks"]
    if all(t["status"] in ("succeed", "failed") for t in tasks):
        break
    time.sleep(4)

# 4) 输出结果
for t in tasks:
    if t["status"] == "succeed":
        print("本地文件:", t["path"])
        print("线上地址:", t["url"])
    else:
        print("失败:", t.get("error"))

FAQ

常见问题

Q1任务一直显示 Dequeued / 生成中很久？▾

服务端排队是正常现象，脚本内部对瞬态错误最多容忍 12 次；极端情况是官方服务繁忙，换个时间段再试即可。

Q2报「无可用的 API Key」？▾

检查 ModelScope_Token.txt 是否存在且有非注释行；或设置环境变量 MODELSCOPE_API_KEY。被限流（429）的 Key 会自动冷却 15 秒后轮换下一个。

Q3提示词直接写中文安全吗？▾

安全。服务端会围绕主体 / 细节 / 镜头 / 光影 / 风格五个维度联想扩写，再翻译成英文，最后拼上模型触发词。想看最终发出去的内容，看任务里的 final_prompt 字段。

Q4为什么带参考图时只能出 1 张？▾

图生图走的是图片编辑 API，官方一次只返回一张，所以带 image_urls 时 count 被强制为 1。

Q5图片保存在哪？▾

run.py 所在目录下的 模型名/ 子目录，文件名格式 月日时分秒_序号-采样器-CFG-步数.png；提示词记录追加在同目录 模型名.md。

Q6端口被占用 / 想换端口？▾

改 run.py 顶部配置区 PORT = 7862（避开 7860 / 8765 / 7877），教程里所有地址同步替换端口即可。

Q7能开放给手机 / 局域网用吗？▾

把 HOST = "127.0.0.1" 改成 "0.0.0.0" 即可，但接口无鉴权，开放前请先加 Key 校验，不建议直接暴露公网。