AI2 / THIRD-PARTY API

AI2 第三方接入指南

用 API Key 调用执行机接口:提交出图任务、轮询状态、下载结果。可选先分析再按分镜出图。

v2.0 · 2026-10-30

版本:2.0 · 更新日期:2026-10-30

面向需要把电商商品图接到 AI2 的第三方系统。通过 HTTPS + API Key 调用执行机接口 /ui/api,提交出图任务、轮询状态、下载结果。

环境 地址
API Base URL https://gen.ai2.lxyi.top
在线试调(可选) https://test.ai2.lxyi.top/api

下文路径均拼在 Base URL 后。协议 HTTPS;JSON 使用 UTF-8;含图片的请求使用 multipart/form-data。暂无完成回调,请轮询任务状态。

阅读顺序:先完成 快速开始(约 10 分钟),跑通鉴权 → 选模型 → 提交出图 → 轮询 → 下载。若需要「先分析出多张分镜方案,再逐张出图」,再阅读 进阶 章节。

版本说明


快速开始

1. 鉴权

每次请求携带:

HTTP
Authorization: Bearer <API_KEY>

先验证 Key:

BASH
export AI2_BASE='https://gen.ai2.lxyi.top'
export AI2_API_KEY='替换为服务方分配的API_KEY'
curl --fail-with-body -sS \
  -H "Authorization: Bearer $AI2_API_KEY" \
  "$AI2_BASE/ui/api/account"

成功时大致返回 {mode:"card", account, requests}:account 含余额与权限,requests 为近期调用记录。Key 无效、账户停用或到期返回 401。

请将 Key 保存在服务端环境变量或凭据库,勿写入前端、URL 或公开仓库。

可选:GET /ui/api/prices 查看收费模板;POST /ui/api/recharge 兑付充值卡(JSON {"card":"…"})。

2. 选择连接与模型(keyId ≠ API Key)

方法 路径 用途
GET /ui/api/choices 默认配置、可用模型连接、代理列表
GET /ui/api/models?keyId=&proxyId= 指定连接下的模型列表

choices 响应示意:

JSON
{
  "defaults": [{"kind": "image", "keyId": 1, "model": "实际模型ID", "proxyId": null}],
  "keys": [{"id": 1, "provider": "服务商ID", "providerName": "服务商名称", "name": "模型连接名称"}],
  "proxies": [{"id": 2, "name": "代理名称"}]
}

说明:

概念 含义
API Key 鉴权凭证,放在 Authorization 头
keyId 账户下某条「模型连接」的编号,取自 keys[].id 或 defaults[].keyId,不是 API Key
model 真实模型 ID,取自 GET /ui/api/models 返回的 models[].id(不要用展示名)

3. 推荐流程:提交 → 轮询 → 下载

TEXT
POST /ui/api/generation-jobs        → 202 {id, state, …}
GET  /ui/api/generation-jobs/{id}   (state 为 queued / running 时继续)
GET  /ui/api/history/{historyId}/image[?download=1]   (state=done 后)

断连不会取消已提交的任务。

POST /ui/api/generation-jobs

multipart/form-data。提交成功返回 HTTP 202,任务在后台继续执行。

表单字段 必填 说明
keyId 是 来自 choices.keys[].id,按文本传递
model 是 来自 models[].id
prompt 见下 完整出图提示词;与 templateId 二选一(见进阶)
templateId 见下 使用服务端出图模板时传,例如 image-default;需执行机已开启模板接口
proxyId 否 同第 2 节
aspectRatio 否 如 1:1、3:4;需要固定比例请显式传入
resolution 否 如 1K、2K;不传则使用模型默认
images[] / images 否 可重复的 JPG/PNG;是否必须参考图取决于模型
title / shotName 否 写入历史记录的展示名

最小接入只需 keyId + model + prompt(+ 可选参考图)。

轮询 GET /ui/api/generation-jobs/{id}

done 后,单任务响应带驼峰字段 historyId。列表接口使用蛇形 history_id,请勿混用。

建议每 2~5 秒轮询一次,并设置等待上限。超时后保留任务 id,稍后继续查询,不要另起付费请求。

下载结果图

HTTP
GET /ui/api/history/{historyId}/image
GET /ui/api/history/{historyId}/image?download=1

返回图片二进制,Content-Type 为实际类型。须携带有效 API Key,不可当作公网直链。请同时检查 HTTP 状态码与 Content-Type,避免把 JSON 错误体当作图片保存。

4. X-Request-Id(幂等)

场景 规则
generation-jobs 必填;建议使用 UUID。允许字符:字母、数字、_、-;长度建议 16~100
同账户 + 同 X-Request-Id 再次提交 jobs 返回原任务,忽略新输入,不创建新任务
同步 analyze / generate 必填 16~100;相同编号再次调用 → 409,不重放旧响应
修改提示词或更换图片 视为新业务,使用新的 Request-Id

一次业务操作生成一个编号并持久保存;网络重试时复用同一编号。

5. 完整示例

curl

BASH
export AI2_BASE='https://gen.ai2.lxyi.top'
export AI2_API_KEY='…'
export AI2_KEY_ID='从choices取得的编号'
export AI2_MODEL='从models取得的出图模型ID'
export AI2_REQUEST_ID="$(uuidgen)"   # 请保存;重试时使用同一个

curl --fail-with-body -sS \
  -H "Authorization: Bearer $AI2_API_KEY" \
  -H "X-Request-Id: $AI2_REQUEST_ID" \
  --form-string "keyId=$AI2_KEY_ID" \
  --form-string "model=$AI2_MODEL" \
  --form-string 'prompt=根据参考图生成商品主图,保持外形和颜色,白色背景。' \
  --form-string 'aspectRatio=1:1' \
  -F 'images[]=@product.jpg;type=image/jpeg' \
  "$AI2_BASE/ui/api/generation-jobs"

202 响应示意:

JSON
{
  "id": "生成任务UUID",
  "state": "queued",
  "error": null,
  "created": 1793300000000,
  "updated": 1793300000000,
  "cancel_requested": false
}

任务也可能直接处于 running 或 done,以返回的 state 为准。使用 -F / --form-string 时不要手动设置 Content-Type(boundary 由客户端生成)。

轮询与下载:

BASH
JOB_ID='上一步返回的id'
curl --fail-with-body -sS -H "Authorization: Bearer $AI2_API_KEY" \
  "$AI2_BASE/ui/api/generation-jobs/$JOB_ID"

# state=done 后:
HISTORY_ID='响应里的historyId'
curl --fail-with-body -sS -H "Authorization: Bearer $AI2_API_KEY" \
  "$AI2_BASE/ui/api/history/$HISTORY_ID/image?download=1" \
  -o generated.image

Python

依赖 requests。环境变量:AI2_API_KEY、AI2_KEY_ID、AI2_MODEL、AI2_REQUEST_ID;当前目录放置 product.jpg。会真实计费。

PYTHON
import os, time
from pathlib import Path
import requests

base = "https://gen.ai2.lxyi.top"
s = requests.Session()
s.headers["Authorization"] = "Bearer " + os.environ["AI2_API_KEY"]

def checked(r):
    r.raise_for_status()
    return r

with open("product.jpg", "rb") as image:
    job = checked(s.post(
        base + "/ui/api/generation-jobs",
        headers={"X-Request-Id": os.environ["AI2_REQUEST_ID"]},
        data={
            "keyId": os.environ["AI2_KEY_ID"],
            "model": os.environ["AI2_MODEL"],
            "prompt": "生成白底商品图,保持商品外形和颜色。",
            "aspectRatio": "1:1",
        },
        files=[("images[]", ("product.jpg", image, "image/jpeg"))],
        timeout=(15, 120),
    )).json()

print("任务编号:", job["id"], flush=True)
deadline = time.monotonic() + 900
while job["state"] in ("queued", "running"):
    if time.monotonic() >= deadline:
        raise TimeoutError("等待结束;保留任务编号稍后继续查询,勿自动重提")
    time.sleep(3)
    job = checked(s.get(
        base + "/ui/api/generation-jobs/" + job["id"], timeout=(15, 30)
    )).json()

if job["state"] != "done":
    raise RuntimeError(f"请人工核对,勿自动重新提交:{job}")

resp = checked(s.get(
    base + "/ui/api/history/" + job["historyId"] + "/image", timeout=(15, 120)
))
mime = resp.headers.get("Content-Type", "").split(";")[0].strip()
suffix = {"image/png": ".png", "image/jpeg": ".jpg"}.get(mime)
if not suffix:
    raise RuntimeError("下载不是预期图片:" + mime)
Path("generated" + suffix).write_bytes(resp.content)
print("已保存 generated" + suffix)

网络异常时直接失败即可,不要自动重复付费请求。若提交响应丢失:使用同账户 + 原 AI2_REQUEST_ID 再次提交相同输入可找回任务;已有任务 id 则只查询。

可选:POST …/generation-jobs/{id}/cancel 取消排队中的任务;仅在明确 failed 时可 POST …/retry(须使用新的 X-Request-Id)。

6. 任务状态

state 含义 接入方处理
queued 已入队,等待执行 继续轮询
running 处理中 继续轮询
done 结果已归档 取 historyId 下载
failed 明确失败 查看 error;可用 retry 新建任务(新 Request-Id)
pending 上游或归档结果不明确 禁止自动重试;保留 id,联系服务方核对
cancelled 排队中已取消 结束

账务状态(reserved / settled / refunded / pending / resolved)与任务 state 分开查看。点数建议使用十进制类型(Decimal / BigDecimal)。生成成功时账务也可能为 pending——不要因此再出一张图。

7. 常见错误码

普通错误体多为 {"error":"原因"};模型相关错误可能带 billed(true 表示可能已计费,需核对,不等于已最终扣点)。

HTTP 常见原因 建议
400 参数、multipart、Request-Id 或提示词不合法 修正参数后重试
401 Key 无效、账户禁用或过期 检查 Key;保留原 Request-Id
402 可用点数不足 充值后再调用
403 权限不足或配置限制 核对账户权限
404 对象不存在、非本账户、或功能未开启 核对 ID / 权限 / 执行机版本
409 同步接口重复 Request-Id;或任务不允许 cancel/retry 按 error 查询原结果;勿当作成功重放
429 并发限制、排队超时或上游限流 退避;pending 任务勿自动重试

其它:405 方法不正确;413 请求体过大;5xx 先核对历史与账户,避免重复付费。

建议:持久保存 Request-Id、任务 id、historyId;仅对明确的 failed 使用 retry;遇到 pending、超时或断连时先核对再决定。


进阶:先分析再出图(可选)

当需要与控制台类似的多张分镜方案(先规划主图、卖点图、细节图等,再逐张生成)时,使用本节。若只需「给定提示词出一张图」,停留在快速开始即可。

流程概览:

TEXT
GET  /ui/api/prompt-templates          (可选,查看可用模板)
POST /ui/api/analyze                   → 200 {text, billing}
解析 text 得到方案 JSON
对方案中每一张图:
  POST /ui/api/generation-jobs         → 轮询 → 下载

1. 提示词模板

HTTP
GET /ui/api/prompt-templates

响应示意:

JSON
{
  "items": [
    {"id": "analyze-default", "kind": "analyze", "name": "默认商品分析"},
    {"id": "image-default", "kind": "image", "name": "默认出图"}
  ]
}
字段 说明
id 模板编号,请求时传给 templateId
kind analyze(分析)或 image(出图)
name 展示名称

列表只返回 id / kind / name,不下发模板正文。内置模板:

id kind 用途
analyze-default analyze 默认商品分析
image-default image 默认出图

请向服务方确认当前执行机是否已开启模板接口。未开启时,请使用完整 prompt 路径。

2. 分析:POST /ui/api/analyze

multipart/form-data。请求头须含 Authorization 与 X-Request-Id(16~100)。成功返回 200 {text, billing}。

两种调用方式互斥(二选一):

方式 字段 说明
使用模板 templateId + input templateId 须为分析类(如 analyze-default);input 为商品数据的 JSON 字符串;服务端套用模板生成完整提示词
自写提示词 prompt 自行提供完整分析提示词(含商品 JSON 与附图说明),不要同时传 templateId

共用字段:

字段 必填 说明
keyId / model 是 使用文本 / 识图模型(kind=text)
proxyId 否 同快速开始第 2 节
images[] 建议 商品参考图;顺序与附图说明一致
references 否 附图清单纯文本。使用模板时可省略:服务端按 images[] 文件名(去掉扩展名)自动生成,例如 img1.jpg → id=img1
feedback 否 二次优化时的反馈文案
title 否 写入历史展示名

互斥规则:

同步分析在相同 X-Request-Id 下再次调用 → 409(不重放)。断连或超时请先查历史与账户,勿盲目重提。

3. input 字段说明(使用模板时)

将下列 JSON 序列化为字符串后放入表单字段 input:

JSON
{
  "title": "陶瓷马克杯",
  "specifications": [],
  "requirements": "白底电商主图风",
  "outputOptions": {
    "platform": "拼多多",
    "aspectRatio": "1:1",
    "resolution": "1K",
    "copyLanguage": "简体中文"
  },
  "pictures": [
    {"id": "main", "type": "main", "name": "主图(首图)", "requirements": ""},
    {"id": "selling-1", "type": "selling", "name": "卖点图", "requirements": ""}
  ]
}
字段 说明
title 商品名称
specifications SKU / 规格列表(如规格值、编码、价格、库存等)。没有规格时传 []
requirements 整单补充说明或风格偏好;没有则 ""
outputOptions.platform 目标平台,如 拼多多、淘宝
outputOptions.aspectRatio / resolution 如 1:1、1K
outputOptions.copyLanguage 文案语言,使用完整名称,如 简体中文、English、日本語;不要写 zh
pictures[] 计划出几张图就写几条;返回方案中的 id 须与此对应
pictures[].type 常见取值:main、white、selling、scene、detail、size、comparison、package、usage;也可自定义
pictures[].requirements 该图单独要求;没有则 ""。例:"突出领口车缝"

建议文件字段名为 images[]。省略 references 时,文件名(不含扩展名)即参考图 id。

4. 解析 text

text 为模型返回的原文,不保证是裸 JSON:可能带 Markdown 代码围栏或前后说明文字。请先剥离围栏再解析。

方案中每张图通常包含 id、copy、promptEnglish、negativePrompt、referenceIds、scene 等字段。后续出图时,可将这些字段填入表单,或自行拼成完整 prompt。

成功响应头可能含 X-Generation-Id(历史记录 id);计费信息在 JSON 的 billing 中。

5. 按分镜出图

对方案中的每一张图:

  1. 使用出图连接与模型(kind=image)。
  2. POST /ui/api/generation-jobs(同步接口 POST /ui/api/generate 同样适用,但更推荐后台任务):
    - 使用模板:templateId=image-default,并从表单传入下列字段(缺省按空字符串):
    platform、aspectRatio、resolution、copyLanguage、copy、promptEnglish、negativePrompt、styleGuide、roleInstruction、visualInstructions、references(正文附图说明,纯文本)。
    - 自写提示词:传入完整出图 prompt,不要传 templateId。
  3. 注意:generation-jobs 另有 JSON 数组字段 references(如 [{"projectImageId":"…"}]),用于关联已保存的项目图 / 历史图,不会写入提示词正文。模板展开用的附图说明请使用表单中的文本字段 references。
  4. 每张图使用独立的 X-Request-Id;images[] 携带该分镜所需的商品参考图。
  5. 轮询 → 取 historyId → 下载(同快速开始)。

templateId 与 prompt 的互斥规则与分析接口相同:双空或双有 → 400;未知 id 或 kind 不符 → 404。

6. 分析请求示例

使用模板

BASH
# 查看可用模板(执行机已开启模板接口时)
curl --fail-with-body -sS -H "Authorization: Bearer $AI2_API_KEY" \
  "$AI2_BASE/ui/api/prompt-templates"

INPUT_JSON='{
  "title": "陶瓷马克杯",
  "specifications": [],
  "requirements": "白底电商主图风",
  "outputOptions": {
    "platform": "拼多多",
    "aspectRatio": "1:1",
    "resolution": "1K",
    "copyLanguage": "简体中文"
  },
  "pictures": [
    {"id": "main", "type": "main", "name": "主图(首图)", "requirements": ""},
    {"id": "selling-1", "type": "selling", "name": "卖点图", "requirements": ""}
  ]
}'

curl --fail-with-body -sS \
  -H "Authorization: Bearer $AI2_API_KEY" \
  -H "X-Request-Id: $(uuidgen)" \
  --form-string "keyId=$AI2_TEXT_KEY_ID" \
  --form-string "model=$AI2_TEXT_MODEL" \
  --form-string "templateId=analyze-default" \
  --form-string "input=$INPUT_JSON" \
  -F 'images[]=@img1.jpg;type=image/jpeg;filename=img1.jpg' \
  "$AI2_BASE/ui/api/analyze"

上例省略了 references:服务端会按文件名 img1 生成附图清单。需要自定义清单时再传文本字段 references;二次优化可增加 feedback。

自写完整 prompt

将完整分析提示词(含商品 JSON 与附图清单)写入 prompt,不传 templateId:

BASH
curl --fail-with-body -sS \
  -H "Authorization: Bearer $AI2_API_KEY" \
  -H "X-Request-Id: $(uuidgen)" \
  --form-string "keyId=$AI2_TEXT_KEY_ID" \
  --form-string "model=$AI2_TEXT_MODEL" \
  --form-string "prompt=$(cat prompt.txt)" \
  -F 'images[]=@img1.jpg;type=image/jpeg' \
  "$AI2_BASE/ui/api/analyze"

prompt.txt 须包含完整的分析指令、商品数据 JSON,以及按顺序排列的附图说明。

同步出图接口 POST /ui/api/generate(成功时直接返回图片字节)仍然可用;新接入更推荐后台任务,避免长连接超时导致误判。


其它能力

如需项目管理、批量或对话能力,请联系服务方。


联调支持

联系服务方时请提供:请求时间(注明时区)、路径、HTTP 状态码、X-Request-Id、任务 id / historyId。请勿在工单或截图中粘贴完整 API Key。

Key 发放、权限、并发、计价与异常账务由服务方受理。