AI追光 · 本地引擎 API

让 AI 和你的程序 调用本地引擎

追光本地引擎开着的时候,你电脑上的 127.0.0.1:7861 就是一个出图、改图、做视频、视频放大的接口。可以交给 AI 批量生成,也可以用 Python、n8n、Dify 调用。生成还是在你自己的显卡上跑,作品不上传。

看 Python 例子

用之前先看这三点

★最简单的用法:交给 AI

  1. 双击桌面「追光本地引擎」,在 本地创作台 切到要用的模型(出图选 FLUX,做视频选 LTX)。
  2. 点上面的「复制给 AI」,把接口说明复制下来。
  3. 打开 Claude Code、Cursor 这类 AI 工具,粘贴进去,再加一句你的要求,例如:
    按上面的接口,把下面 10 个分镜提示词都生成 16:9 的图片,存到 D:\分镜 文件夹。
  4. AI 会自己写脚本,一条条交给引擎生成,做完告诉你。
点一下,看看这台电脑的引擎能不能被调用

1两个地址

地址做什么
http://127.0.0.1:7860引擎管家:查看状态、切换模型、关闭模型。
http://127.0.0.1:7861生成接口:出图、改图、做视频、视频放大,以及查进度、取结果。

所有 POST 请求都要带请求头 Origin: http://localhost,否则会被拒绝(403)。这是为了防止别的网站偷偷遥控你的引擎;你自己的脚本加上这一行就行。

2查看状态、切换模型

请求说明
GET /status(7860)返回 state(ready 已就绪 / loading 载入中 / stopped 已关闭 / crashed 出错)、model(当前模型)、显卡和内存占用、已装的模型列表。
POST /start?model=flux(7860)切换模型:flux = FLUX.2 klein(出图、改图、多图合成),zimage = Z-Image(图里写中文字),ltx = LTX-2.5 视频。然后反复查 /status,等 state 变成 ready。
POST /stop(7860)关闭模型,释放显存和内存。

3出图 / 改图(FLUX 或 Z-Image)

POST http://127.0.0.1:7861/sdcpp/v1/img_gen,返回 {"id": "任务编号"}。

{
  "prompt": "雨夜的老式公交站台,一位七十岁的中国老爷爷撑着黑伞,电影感,真实摄影风格",
  "width": 1344, "height": 768,
  "seed": 12345,
  "ref_images": [],
  "sample_params": { "sample_method": "euler", "sample_steps": 4, "guidance": { "txt_cfg": 1.0 } },
  "vae_tiling_params": { "enabled": true },
  "output_format": "png"
}
参数说明
prompt提示词,中英文都行。
width / height常用尺寸:16:9 = 1344×768,9:16 = 768×1344,1:1 = 1024×1024,4:3 = 1280×960;2K:1920×1088。宽高要是 16 的倍数。
seed种子。同提示词 + 同种子 = 同一张图。
ref_images改图 / 多图合成用的参考图,最多 4 张,每张是 data:image/png;base64,...。提示词里用「图1、图2」指代。只有 FLUX 支持,Z-Image 留空。
sample_stepsFLUX 用 4(更细致可用 6、8);Z-Image 用 8。

4查进度、取结果

GET http://127.0.0.1:7861/sdcpp/v1/jobs/任务编号,每隔 1~2 秒查一次:

status意思
queued排队中(引擎一次只做一条,按提交顺序来)。
running生成中。视频任务的 progress 里有阶段和百分比。
completed完成。图片:result.images[0].b64_json 是 PNG 的 base64,解码存成 .png。视频:result.video_url 是文件地址,GET http://127.0.0.1:7861 + 这个地址,下载就是 mp4。
failed失败,原因在 error 里。
cancelled已取消。

取消:POST /sdcpp/v1/jobs/任务编号/cancel。出图只能取消还在排队的;视频生成中也能停。

5做视频(LTX-2.5)

先切到 ltx。然后 POST http://127.0.0.1:7861/sdcpp/v1/vid_gen,返回任务编号,查进度的方法同上。

{
  "prompt": "场景:雨夜老式公交站台…… 正文:固定镜头,缓慢推近。老爷爷望着远处,小声说:“来了。” 无背景音乐 无字幕",
  "width": 1280, "height": 704,
  "video_frames": 121, "fps": 24,
  "seed": 12345,
  "model_type": "ltx2_25_22B_distilled",
  "init_image": null, "end_image": null, "ref_images": null,
  "sample_params": { "sample_method": "euler", "sample_steps": 8, "guidance": { "txt_cfg": 1.0 } },
  "vae_tiling_params": { "enabled": true, "temporal_tiling": true, "tile_size_x": 16, "tile_size_y": 16,
                         "extra_tiling_args": "temporal_tile_frames=2,temporal_tile_overlap=1" },
  "output_format": "webm"
}
参数说明
video_frames帧数 = 秒数 × 24 + 1。5 秒 = 121,6 秒 = 145,8 秒 = 193,10 秒 = 241(最长 10 秒)。
width / height720P:横屏 1280×704,竖屏 704×1280,1:1 960×960。1080P:1920×1088(8G 显卡建议最多 5 秒)。480P:832×480。
init_image / end_image首帧 / 尾帧,data:image/png;base64,...,不用就填 null。
ref_images全能参考:最多 5 张图,场景图放第 1 张(这时不能同时用首帧)。ref_bg:第 1 张是不是场景,默认 true。
prompt建议用中文写,台词放在中文引号里。LTX 会同时生成声音和对白。

720P 5 秒一条,8G 显卡大约 3~4 分钟;第一次用会先下载模型,要等更久。

6视频放大 / 补帧

也在 LTX 模型下用。POST http://127.0.0.1:7861/sdcpp/v1/vid_up:

{ "video": "data:video/mp4;base64,....", "spatial": "flashvsr*1.5", "temporal": "", "seed": 1 }
spatial(放大)flashvsr*1.5(720P → 1080P,推荐)、flashvsr*2、lanczos*1.5、lanczos*2,或留空不放大。
temporal(补帧)rife*2(24fps → 48fps,动作更顺),或留空。

两个不能同时留空。第一次用会先下载放大模型。

7让作品出现在本地创作台

脚本把图片或视频存到硬盘后,再「登记」一下,本地创作台就会自动把它收进作品墙,标上「API 生成」,和网页做的作品一样能放大、引用提示词、当参考图、送进剪辑台。创作台没开也没关系,下次打开时一起收进来。

POST http://127.0.0.1:7860/inbox(注意是 7860 管家),同样要带 Origin: http://localhost:

{ "path": "D:\\分镜\\shot01.png", "prompt": "雨夜的老式公交站台……", "seed": 12345, "model": "flux" }
参数说明
path文件的完整路径(必填)。支持 png、jpg、webp、mp4、webm,300MB 以内。
prompt / seed / model选填。写上以后,创作台里能「引用提示词」「复用种子」。model 填 flux、zimage 或 ltx。

收件箱需要新版引擎(管家 1.3)。旧版引擎照样能用上面的接口生成,只是作品不会自动出现在创作台;重新运行一次「安装 / 更新引擎」就有了。没更新之前,也可以把文件直接拖进创作台。

8完整例子(Python)

存成 aizg_gen.py,装好 Python 后运行 python aizg_gen.py。只用到 Python 自带的库,不用另外安装。

import base64, json, os, time, urllib.request

MGR, API = "http://127.0.0.1:7860", "http://127.0.0.1:7861"
HDR = {"Content-Type": "application/json", "Origin": "http://localhost"}

def call(url, body=None):
    req = urllib.request.Request(url, data=None if body is None else json.dumps(body).encode(),
                                 headers=HDR, method="GET" if body is None else "POST")
    with urllib.request.urlopen(req, timeout=60) as r:
        return json.loads(r.read())

def use_model(m):                      # flux / zimage / ltx
    st = call(MGR + "/status")
    if st["model"] != m or st["state"] != "ready":
        call(MGR + "/start?model=" + m, {})
        while call(MGR + "/status")["state"] != "ready":
            print("模型载入中……"); time.sleep(5)

def wait(job_id):
    while True:
        s = call(API + "/sdcpp/v1/jobs/" + job_id)
        if s["status"] == "completed": return s["result"]
        if s["status"] in ("failed", "cancelled"): raise RuntimeError(s.get("error") or s["status"])
        time.sleep(2)

def to_studio(path, prompt, seed, model):   # 登记到收件箱:作品自动出现在本地创作台(需要新版引擎)
    try: call(MGR + "/inbox", {"path": os.path.abspath(path), "prompt": prompt, "seed": seed, "model": model})
    except Exception: pass

def image(prompt, path, w=1344, h=768, seed=1):
    use_model("flux")
    job = call(API + "/sdcpp/v1/img_gen", {
        "prompt": prompt, "width": w, "height": h, "seed": seed, "ref_images": [],
        "sample_params": {"sample_method": "euler", "sample_steps": 4, "guidance": {"txt_cfg": 1.0}},
        "vae_tiling_params": {"enabled": True}, "output_format": "png"})
    res = wait(job["id"])
    open(path, "wb").write(base64.b64decode(res["images"][0]["b64_json"]))
    to_studio(path, prompt, seed, "flux")
    print("图片已保存:", path)

def video(prompt, path, seconds=5, w=1280, h=704, seed=1):
    use_model("ltx")
    job = call(API + "/sdcpp/v1/vid_gen", {
        "prompt": prompt, "width": w, "height": h, "seed": seed, "fps": 24,
        "video_frames": seconds * 24 + 1, "model_type": "ltx2_25_22B_distilled",
        "init_image": None, "end_image": None, "ref_images": None,
        "sample_params": {"sample_method": "euler", "sample_steps": 8, "guidance": {"txt_cfg": 1.0}},
        "vae_tiling_params": {"enabled": True, "temporal_tiling": True, "tile_size_x": 16, "tile_size_y": 16,
                              "extra_tiling_args": "temporal_tile_frames=2,temporal_tile_overlap=1"},
        "output_format": "webm"})
    res = wait(job["id"])
    with urllib.request.urlopen(urllib.request.Request(API + res["video_url"], headers=HDR)) as r:
        open(path, "wb").write(r.read())
    to_studio(path, prompt, seed, "ltx")
    print("视频已保存:", path)

if __name__ == "__main__":
    image("雨夜的老式公交站台,一位七十岁的中国老爷爷撑着黑伞,电影感,真实摄影风格", "test.png")
    # video("雨夜公交站台,老爷爷望着远处,小声说:“来了。” 无背景音乐 无字幕", "test.mp4")

?常见问题

连不上 / 报 Connection refused

引擎没开,或者模型还在载入。双击桌面「追光本地引擎」,等黑色窗口显示「已就绪」。

报 403 origin not allowed

POST 请求没带 Origin: http://localhost 请求头。

报 503 / 还在载入

视频模型正在载入,过一会儿再提交;或先查 /status,等 ready。

能同时提交很多条吗?

可以一次提交多条,引擎会排队一条条做,用 /sdcpp/v1/jobs/任务编号 分别查。显卡同一时间只做一条,不会更快。

API 生成的作品在哪里?

脚本存到你指定的文件夹;登记到收件箱(第 7 步)后,也会出现在本地创作台的作品墙。

能接 MCP(让 Claude 等直接调用)吗?

正在做「追光本地引擎 MCP 插件」,做好会放在这一页。