AI2 API 接入指南

版本：1.0 · 更新日期：2026-10-29

AI2 API 提供图片生成、图像分析、批量生成和多轮对话能力。使用服务方分配的 API Key 即可从服务端调用，无需登录或维护 Cookie。

阅读导航

首次接入建议依次阅读「接入地址」「API Key 鉴权」「配置与模型」「后台单张出图」。后续可按需接入历史下载、同步分析、项目管理、批量生成和 AI 对话。文中所有 Key、模型名称和业务 ID 均为占位示例。

1. 接入地址与调用流程

• Base URL：https://gen.ai2.lxyi.top，下文路径均拼接在此地址后。
• 协议：HTTPS；JSON 使用 UTF-8；文件请求使用 multipart/form-data 或图片原始字节。
• 鉴权：每次请求带 Authorization: Bearer <API_KEY>。
• 接口格式：使用本文定义的 HTTP 路径与参数。接入现成 SDK 时，请确认其支持自定义请求格式。
• keyId 是可用模型连接的编号，与鉴权用的 API Key 不同；从配置接口获取。
• 推荐流程：带 Key 获取可用配置和模型 → 提交后台出图任务 → 轮询任务 → 使用历史 ID 下载图片。

调用能力、额度和并发上限以所分配账户为准。任务通过轮询查询结果，暂不提供完成回调 Webhook。建议由您的服务端保存并使用 API Key。

2. API Key 鉴权

向服务方申请 API Key，并在每次请求头中携带：

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"

API Key 用于所有业务请求，包括任务提交、状态查询和图片下载。请将其保存在服务端环境变量或凭据管理系统中，不要放入公开网页或 URL 参数。

Key 的有效期与权限由服务方设置。Key 被撤销、账户停用或到期时返回 HTTP 401；请联系服务方确认或更换 Key。

3. 配置、模型与账户

choices 结构示意（编号和模型仅为示例，以实际返回为准）：

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

models 的 models[] 元素包含 id,name,type,aspectRatios,resolutions。如响应存在 errors[]，请检查其中的错误消息，不能仅凭 HTTP 200 认定模型列表完整可用。接口仅返回本账户可见的连接与模型；调用还需满足相应的计价配置及余额要求。

所有模型调用的共同字段：

4. 后台单张出图（推荐）

提交成功后返回 HTTP 202，后台继续处理。客户端断连不会取消任务。

POST /ui/api/generation-jobs

请求类型：multipart/form-data。请求头 X-Request-Id 必填，允许 1～100 位字母、数字、下划线、连字符，建议始终使用 UUID，兼容其它付费接口的 16～100 位要求。

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' \
  --form-string 'adoption=preview' \
  -F 'images[]=@product.jpg;type=image/jpeg' \
  "$AI2_BASE/ui/api/generation-jobs"

使用 curl -F 时不要手工设置 Content-Type，由客户端生成 multipart boundary。--form-string 可避免提示词开头的 @ 等字符被 curl 当作文件指令。

复用已保存图片时，将 references 作为普通文本字段：

[{"projectImageId":"img1"},{"historyId":"历史成图UUID"}]

projectImageId 需要同时提供 projectId，且图片已上传；historyId 必须是本人历史中的图片结果。可与文件上传同时使用，顺序是本次上传图片在前、references 数组在后。接口不支持把任意公网图片 URL 直接作为这个字段。

202 响应示意：

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

任务可能已立即进入 running 或完成；以实际 state 为准。同一账户和同一 X-Request-Id 再次提交返回原任务，忽略新请求中的输入，不创建新任务。 更改提示词或参考图属于新操作，需使用新编号。

查询、取消和重试

单任务响应使用 historyId；列表响应使用 history_id、shot_id、cancel_requested。请勿混用两种命名。

建议每 2～5 秒轮询一次，自行设置等待期限；停止等待后保留任务 ID，下次继续查询。服务恢复后，排队任务继续执行；执行结果不明确的任务可能转为 pending，需联系服务方核对。

adoption 为 adopted（已自动采用）、available（可用候选）或 conflict（版本 / 当前选择 / 提交顺序变化，未自动采用）。这三种值的区别不影响通过 historyId 下载已归档结果。

Python 完整调用示例

依赖 requests。设置环境变量 AI2_API_KEY、AI2_KEY_ID、AI2_MODEL、AI2_REQUEST_ID；请求编号由调用方为每次业务操作生成并保存，网络重试使用原编号。当前目录准备 product.jpg。示例会发起真实模型调用并按账户规则计费。

import os
import time
from pathlib import Path
import requests

base = "https://gen.ai2.lxyi.top"
session = requests.Session()

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

session.headers["Authorization"] = "Bearer " + os.environ["AI2_API_KEY"]

with open("product.jpg", "rb") as image:
    job = checked(session.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", "adoption": "preview"},
        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(session.get(base + "/ui/api/generation-jobs/" + job["id"],
                              timeout=(15, 30))).json()

if job["state"] != "done":
    raise RuntimeError(f"请核对任务，勿自动重新提交：{job}")
response = checked(session.get(base + "/ui/api/history/" + job["historyId"] +
                              "/image", timeout=(15, 120)))
mime = response.headers.get("Content-Type", "").split(";")[0].strip()
suffix = {"image/png": ".png", "image/jpeg": ".jpg"}.get(mime)
if suffix is None:
    raise RuntimeError("下载响应不是预期的图片：" + mime)
Path("generated" + suffix).write_bytes(response.content)
print("图片已保存；请通过历史详情或账户调用记录核对最终账务。")

示例对网络异常直接报错，不自动重复付费请求。提交响应丢失时，可用同一账户和原 AI2_REQUEST_ID 重新提交相同输入找回任务；已取得任务编号则直接查询。

5. 历史、图片下载与账务

history 的 projectId 不传查全部，none 查未分类，项目 UUID 查指定项目。图片读取需要有效 API Key，不能作为无需认证的公网图链给外部系统直接抓取。需要外部公开展示时，由第三方服务端下载后存入自己的存储。

curl --fail-with-body -sS -H "Authorization: Bearer $AI2_API_KEY" \
  "$AI2_BASE/ui/api/history/替换为historyId/image?download=1" \
  -o generated.image

请同时检查 HTTP 状态码和 Content-Type，避免把 JSON 错误体当图片。

账务状态与生成状态分别判断：reserved 处理中，settled 已按用量结算，refunded 明确未发出 / 未计费失败，pending 待核对，resolved 已核对。点数采用十进制字符串，建议用 Decimal / BigDecimal 计算。

账户有可用余额才允许调用；不预先冻结新调用费用，也不设单次扣费封顶，完成后可扣为负数。模型、服务商、分辨率需同时满足权限和有效收费模板。生成成功也可能因上游用量不完整而账务 pending；不要因此重新出图。

6. 同步分析与同步出图

请求均为 multipart/form-data，使用 keyId、model、proxyId、prompt、images[]；出图还支持 aspectRatio、resolution；可传 projectId、title、shotName 关联历史。references 资源复用仅后台任务接口支持，同步接口需上传文件。

请求必须携带 X-Request-Id，16～100 位字母、数字、下划线、连字符。同步接口相同编号重复调用返回 409，不重放旧响应。推荐新集成使用后台出图接口；同步分析仍需等待 HTTP 返回。

curl --fail-with-body -sS -H "Authorization: Bearer $AI2_API_KEY" \
  -H "X-Request-Id: $(uuidgen)" \
  --form-string "keyId=$AI2_KEY_ID" \
  --form-string 'model=替换为文本或识图模型ID' \
  --form-string 'prompt=请分析商品外观、材质、用途与卖点。' \
  -F 'images[]=@product.jpg;type=image/jpeg' \
  "$AI2_BASE/ui/api/analyze"

成功响应头 X-Generation-Id 是历史 ID；同步出图另有 X-Duration-Ms，有账务时带 X-Billing-State、X-Points-Charged。分析的 billing 在 JSON 内。

同步请求在服务器并发槽满时最多排队 10 分钟，超时 429；还会受到客户端、反向代理和上游超时影响。断连或超时不代表未调用 / 未扣费，应检查历史与账户记录。

7. 项目与分镜（按需接入）

项目用于管理一组参考图、分镜和生成结果。创建项目只需名称；也可以不建项目直接出图。

增量保存 changes 支持 form、plan、images、shotsUpsert、removedShots、shotOrder。先读取最新 version 再提交；409 后重新读取并合并，不能直接覆盖。兼容全量 {version,state}，建议新接入使用增量。

{
  "version":0,
  "changes":{
    "shotsUpsert":[{"id":"main","name":"主图","promptEnglish":"White background product photo"}]
  }
}

项目内分镜 ID 为 1～100 位字母、数字、下划线、连字符。自动采用结果要求分镜内容版本、选择版本及最新提交序号仍匹配；与图片无关的名称 / 排序变化不影响内容版本。生成时可传 adoption=preview，由业务系统自行决定使用哪张结果。

8. Vertex 批量出图（可选）

批量能力需由服务方开通，并使用支持 Vertex 批量生成的模型连接。请先调用 options 确认可用性。

表单字段为 keyId、model、proxyId、projectId、title、aspectRatio、resolution、items、anchorShot。resolution 只允许空或 1K；每批 1～200 项。

items 是 JSON 数组字符串：

[
  {"shotId":"main","shotName":"主图","prompt":"生成白底商品图","files":["ref1"],"aspectRatio":"1:1"},
  {"shotId":"detail","shotName":"细节图","prompt":"生成商品细节图","files":["ref1"],"aspectRatio":"3:4"}
]

图片作为 multipart 文件字段 ref1 上传；items[].files 必须与文件字段名一致，同一图片只需上传一次。文件字段名限 1～60 位字母、数字、下划线、连字符。项目分镜可另传 contentVersion、currentResultId。

建议始终传 X-Request-Id（1～100 位上述字符）；同账户同编号返回原批次，不传则没有本项幂等保护。两段批量时 anchorShot 指定主图 shotId，其余依赖项 files 中加入 @main，服务端等主图完成后再提交依赖项。

查询返回各批次 items，单项含 idx、shot_id、shot_name、state、history_id、error。批次可能部分成功（partial），逐项检查并下载有 history_id 的结果。批量的 pending / 提交结果不明确时，同样不能自动重复创建付费批次。options 中 discount 为批量配置提示，最终扣点以账务记录为准。

9. AI 对话（可选）

带附件时 send 改用 multipart，同名文本字段加可重复 files[]；支持类型、大小和数量取决于模型策略。纯文本 text 为 1～12000 字符，带附件可空。

send 请求头加 Accept: text/event-stream 开启 SSE，事件依次为 start（已保存用户消息）、delta（{"text":"新增文字"}）、done（完整会话），异常用 error（error、billed）。HTTP 已进入流后，不能只凭 HTTP 200 认定成功；必须处理 done / error，断线后读取会话核对，不能直接重发。

10. 错误码、限额与重试约定

普通错误 JSON 为 {"error":"原因"}；模型执行相关错误可能另有 billed 布尔值。billed:true 表示可能已计费，需核对，不代表已完成最终扣点。没有 billed 字段也不能据此断定上游未执行。

multipart 单个文本字段最大 512 KiB，文本与文件字段合计最多 1000 个。项目参考图上传单张最大 25 MiB；生成请求总大小和参考图数量还受所选模型与服务配置限制。遇到 413 时请减小输入或联系服务方确认限额。

最关键的接入约定：保存业务请求编号、任务 ID、历史 ID；区分任务与账务状态；仅对明确 failed 的普通任务使用 retry；pending、超时和断连先核对。不同账户的数据相互隔离，无权限对象通常返回 404。API Key 是访问凭据；keyId、model、prompt 和 X-Request-Id 是各自独立的业务参数，请按接口要求填写。

11. 真实调用数据

以下为 AI2 实际生成历史的脱敏快照，采集时间为 2026-10-29 22:11:01（America/Los_Angeles，UTC−07:00）。采集时共有 408 条已归档记录；本次取最近 24 条，其中图片生成 19 条、分析 5 条，均已结算。

最近 8 条记录：

统计仅覆盖所选已归档记录，不包含全部失败或未完成调用，不能据此计算整体成功率。耗时取记录的 durationMs；扣点是历史实际结算值，非人民币金额、固定报价或服务时限承诺。记录不含账户、Key、提示词或图片内容。

12. 接入支持

联调或异常核对时，请向服务方提供请求时间、接口路径、HTTP 状态码、X-Request-Id，以及已获得的任务 ID 或历史 ID。请勿在问题描述、截图或普通日志中提供完整 API Key。

Key 发放、权限开通、并发额度、计价与异常账务核对均由服务方受理。