版本: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 分钟),跑通鉴权 → 选模型 → 提交出图 → 轮询 → 下载。若需要「先分析出多张分镜方案,再逐张出图」,再阅读 进阶 章节。
版本说明
- API Key 鉴权与
generation-jobs后台出图:当前可用。 - 服务端提示词模板(
templateId:analyze-default/image-default):请向服务方确认当前执行机是否已开启模板接口。未开启时,请自行传入完整prompt(行为与旧客户端一致)。
快速开始
1. 鉴权
每次请求携带:
Authorization: Bearer <API_KEY>
先验证 Key:
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 响应示意:
{
"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(不要用展示名) |
- 出图:使用
defaults中kind=image的默认,或自行选择keys[].id。 - 识图 / 分析:使用
kind=text的连接与模型。 - 再请求
GET /ui/api/models?keyId=<编号>&proxyId=: proxyId省略或空字符串:使用该连接的默认代理;none:不走代理;- 数字字符串:指定
proxies[].id。 models[]含id, name, type, aspectRatios, resolutions。若响应含errors[],不能仅凭 HTTP 200 认定列表全部可用。
3. 推荐流程:提交 → 轮询 → 下载
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,稍后继续查询,不要另起付费请求。
下载结果图
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
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 响应示意:
{
"id": "生成任务UUID",
"state": "queued",
"error": null,
"created": 1793300000000,
"updated": 1793300000000,
"cancel_requested": false
}
任务也可能直接处于 running 或 done,以返回的 state 为准。使用 -F / --form-string 时不要手动设置 Content-Type(boundary 由客户端生成)。
轮询与下载:
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。会真实计费。
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、超时或断连时先核对再决定。
进阶:先分析再出图(可选)
当需要与控制台类似的多张分镜方案(先规划主图、卖点图、细节图等,再逐张生成)时,使用本节。若只需「给定提示词出一张图」,停留在快速开始即可。
流程概览:
GET /ui/api/prompt-templates (可选,查看可用模板)
POST /ui/api/analyze → 200 {text, billing}
解析 text 得到方案 JSON
对方案中每一张图:
POST /ui/api/generation-jobs → 轮询 → 下载
1. 提示词模板
GET /ui/api/prompt-templates
响应示意:
{
"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 |
否 | 写入历史展示名 |
互斥规则:
templateId与prompt二选一;两者都空或两者都有 → 400- 未知
templateId,或kind不符(例如把image-default用于 analyze)→ 404 - 只传
prompt的旧客户端行为保持不变
同步分析在相同 X-Request-Id 下再次调用 → 409(不重放)。断连或超时请先查历史与账户,勿盲目重提。
3. input 字段说明(使用模板时)
将下列 JSON 序列化为字符串后放入表单字段 input:
{
"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. 按分镜出图
对方案中的每一张图:
- 使用出图连接与模型(
kind=image)。 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。- 注意:
generation-jobs另有 JSON 数组字段references(如[{"projectImageId":"…"}]),用于关联已保存的项目图 / 历史图,不会写入提示词正文。模板展开用的附图说明请使用表单中的文本字段references。 - 每张图使用独立的
X-Request-Id;images[]携带该分镜所需的商品参考图。 - 轮询 → 取
historyId→ 下载(同快速开始)。
templateId 与 prompt 的互斥规则与分析接口相同:双空或双有 → 400;未知 id 或 kind 不符 → 404。
6. 分析请求示例
使用模板
# 查看可用模板(执行机已开启模板接口时)
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:
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 发放、权限、并发、计价与异常账务由服务方受理。