8848AI 工具指南

返回文档首页

8848生图API说明

网站后台接入：提交 → 查询 → 下载转存。不限定后端语言。

Key 只配置在你们服务器，用户继续使用你们自己的生成按钮、任务中心和资产库。后台自动处理编号，最终用户不用操作。

标准 HTTP 接入方案终端完整命令同步接口

更新：2026-10-15 · 完整请求与返回示例 · 文生图 / 参考图

网站后台标准 HTTP 接入方案

不限制后端语言。由你们的网站后台调用，前端继续使用你们自己的生成按钮、任务中心和资产库。

最短链路：提交 → 查这一单 → 成功一张下载一张 → 存到你们自己的资产库。单张查询是可选项，不必多调用。

下面是完整 HTTP 调用的 curl 表达，供开发人员对应实现，并非要求最终用户运行。YOUR_API_KEY 换成服务器后台配置的真实 Key；响应中的编号均为结构示例，不是可以直接查询的真实任务。所有操作均由后台代码自动衔接，用户不用复制编号。

1. 提交生图任务

接口：POST https://api.884819.xyz/v1/images/async

请求头：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: movieone-image-order-001

Idempotency-Key 使用你们自己的唯一业务任务号，发送前将它与完整请求正文保存。一个业务任务固定一个键；新任务使用新键。

文生图：完整请求

curl --fail-with-body 'https://api.884819.xyz/v1/images/async' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: movieone-image-order-001' \
  -d '{
    "items": [
      {
        "client_ref": "shot-001",
        "model": "gpt-image-2.5-sunburst",
        "prompt": "海边日落，一位年轻人站在码头上，电影写实风格",
        "n": 1
      }
    ]
  }'

参考图：改用这条完整请求

与文生图二选一，不要为同一个业务任务同时提交两条。

先把参考图上传到你们自己的文件存储，取得平台可以下载的完整图片 URL。将下面 images[0].image_url 的说明文字替换为该 URL。

curl --fail-with-body 'https://api.884819.xyz/v1/images/async' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: movieone-image-order-002' \
  -d '{
    "items": [
      {
        "client_ref": "shot-002",
        "model": "gpt-image-2.5-sunburst",
        "prompt": "保留参考图中的人物和服装，将背景改为海边日落，电影写实风格",
        "n": 1,
        "images": [
          {"image_url": "此处替换为你们存储上的完整HTTP或HTTPS图片URL"}
        ],
        "input_fidelity": "high"
      }
    ]
  }'

参考图须为可下载的 PNG / JPEG / WebP，不传本地路径、Base64、blob 地址或需要网页登录的页面。签名 URL 的有效期须覆盖排队与执行。本示例为 Sunburst 单参考图。

接单响应

首次受理 HTTP 202：

{
  "batch_id": "aib_EXAMPLE",
  "total": 1,
  "status": "queued",
  "poll_interval": 5
}

后台读取并保存 batch_id。这里不返回 task_id 是正常的，第 2 步取得；只生成一张也走同样流程。

你们的提交接口此时即可向网页返回自己的任务号和“排队中”，不要保持网页请求一直等待出图。后续由后台任务执行，用户关闭网页不应取消已提交的生成任务。

2. 查询这一单，取得每张图的编号与状态

接口：GET https://api.884819.xyz/v1/images/async/{batch_id}

将路径中的 aib_EXAMPLE 换成第 1 步真实响应的 batch_id。后台每约 5 秒执行一次：

curl --fail-with-body 'https://api.884819.xyz/v1/images/async/aib_EXAMPLE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

排队中的响应结构示例：

{
  "batch_id": "aib_EXAMPLE",
  "total": 1,
  "counts": {
    "queued": 1,
    "running": 0,
    "succeeded": 0,
    "failed": 0,
    "unknown": 0
  },
  "data": [
    {
      "task_id": "ait_EXAMPLE",
      "client_ref": "shot-001",
      "model": "gpt-image-2.5-sunburst",
      "status": "queued",
      "created_at": 1792060000
    }
  ],
  "poll_interval": 5
}

data[].task_id：每张图的平台编号，排队时就能取得，后台自动保存。
data[].client_ref：你们提交时的业务图片编号，原样返回，用来对应分镜、角色或素材。
data[].status：该张图的状态。

status	你们后台怎么处理
`queued`	标记排队中，稍后继续查
`running`	标记生成中，稍后继续查
`succeeded`	立即执行第 3 步下载，不等整单完成
`failed`	保存该项 `error.code`、`error.message` 并显示失败
`unknown`	标记待核对，不自动重新提交

成功项增加 url 和 expires_at 字段。过期后可能仍为 succeeded，但有 file_state: "expired" 且无有效 URL，不能按成功状态认定文件仍可领取。

3. 下载到你们的服务器或对象存储

接口：GET https://api.884819.xyz/v1/images/async/tasks/{task_id}/content

ait_EXAMPLE 由第 2 步的 data[].task_id 自动代入。

curl --fail 'https://api.884819.xyz/v1/images/async/tasks/ait_EXAMPLE/content' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -o result-image \
  -w 'Content-Type: %{content_type}\n'

返回 HTTP 200，响应体是图片二进制，不是 JSON。按 Content-Type 使用 .png、.jpg 或 .webp 扩展名。后台应流式保存文件或上传到自己的对象存储。

也可以对查询响应中返回的完整 url 直接发送 GET，不带 Authorization；不得截断或改写签名参数，不公开该临时凭据。

下载并转存成功后，将你们自己的图片地址写入资产库，再把网站任务标记为完成。网页展示你们自己的资产地址，不要把8848临时链接当永久图片地址。

平台结果当前自图片就绪起约 30 分钟可领取，以每张 expires_at（Unix 秒）为准；查询不延长有效期，正常过期不退款。转存失败但仍在有效期内，只重试查询或下载，不重新生成。

4. 接到现有网站任务系统

你们现有的生成入口、任务中心、资产页可以继续使用。在后端的图片供应商适配层完成以下逻辑：

用户点击生成
  → 你们后台创建自己的业务任务
  → 保存唯一幂等键和原始提交正文
  → 提交8848异步接口并保存batch_id
  → 将自己的任务号返回网页

后台任务继续执行
  → 每约5秒查询batch_id
  → 按client_ref关联业务图片，保存task_id
  → queued/running：更新进度，继续查询
  → succeeded：下载到自己的存储，写入资产库，再标记完成
  → failed：记录错误并显示失败
  → unknown：标记待核对，不自动重新生成

用户打开任务中心或刷新网页
  → 查询你们自己的任务记录
  → 展示生成状态或自有资产地址

后台至少持久化：自己的业务任务号、所属用户/项目、幂等键、原请求正文、batch_id、各项 client_ref/task_id、状态、expires_at、转存状态和自有资产地址。API Key 单独存放在服务器密钥配置中，不返回浏览器、不写日志。

批量：一批 1–100 项，每项一张、n 只能为 1 或省略。50 张写 50 个 item，并使用不同 client_ref。每张独立处理，按 task_id 去重转存；不代表整批同时生成。若自行使用分页，上一页 next_after 填到 after，每轮重新从第一页开始，避免漏掉后来成功的图片。

5. 超时和重复请求必须这样处理

情况	处理
提交超时、连接中断、未收到响应	使用原幂等键、原正文重放，不能换键重新生成
同用户、同键、同正文重放	HTTP 200 返回原批次，不新建任务；实时进度仍需查询
同键却修改正文	HTTP 409，检查业务任务与请求内容
等得久、网页关闭或刷新	后台继续查询原任务，不重提、不改走同步重做
查询或下载暂时失败	重试查询或下载，不调用生成接口；有 Retry-After 时遵守
任务 unknown	联系平台核对，不当作可安全重做
下载 HTTP 410	图片已过期或不可用，不能通过重新查询恢复，不自动重新生成

其他常见错误：400/413 检查正文；401/403 检查 Key、模型权限或下载签名；402 检查账户/令牌额度；404 检查编号及所属用户；429/503 按提示退避。

异步不是“换一个 URL 的同步接口”。目前没有本方案中的完成回调，需要你们后台主动查询；生成耗时和排队不作固定分钟数承诺。提交、轮询、转存必须能在网页请求结束后继续执行。

可选：只查单张

已经保存 task_id 后，可以用单张接口代替整批查询。不是必做步骤。

curl --fail-with-body 'https://api.884819.xyz/v1/images/async/tasks/ait_EXAMPLE' \
  -H 'Authorization: Bearer YOUR_API_KEY'

直接返回单张任务对象，字段为 task_id、client_ref、model、status、created_at 等，没有外层 data 数组；成功时增加 url、expires_at。

适用范围

异步支持：gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst。示例统一使用 Sunburst，参考图先接单张。
令牌须有对应模型、分组权限和额度，沿用对应模型/分组的同步计价；查询、下载不会创建新的生图任务。
异步不要传 response_format、stream；本方案不涉及修改你们现有同步线路。
全部编号、时间戳和 Key 为结构说明占位值，不是本轮新付费实测输出。未为编写本方案新增生成或扣费。

可选：本机终端完整命令（自动生成并下载）

这一段用于开发人员在 Mac / Linux 终端操作，不是嵌入网页的前端代码。网站正式接入请使用上面的后台 HTTP 方案，不要把 Key 写进浏览器。

完整命令：先复制这一整段

API_KEY 引号里填你的完整 API Key；PROMPT 三引号里填提示词；REFERENCE_IMAGE_URL 留空为文生图，填完整图片 URL 为参考图生图。首次提交会生成一张并计费。

python3 -I - <<'PY'
API_KEY = "sk-替换为你的API-Key"
PROMPT = """白色背景上的咖啡杯产品摄影"""
REFERENCE_IMAGE_URL = ""

import hashlib
import json
from pathlib import Path
import time
import urllib.error
import urllib.request
import uuid

if not API_KEY or "替换" in API_KEY:
    raise SystemExit("请先替换第一行 API_KEY，再运行整段命令。")
if not PROMPT.strip():
    raise SystemExit("请填写第二行 PROMPT。")

item = {"model": "gpt-image-2.5-sunburst", "prompt": PROMPT, "n": 1}
if REFERENCE_IMAGE_URL:
    item["images"] = [{"image_url": REFERENCE_IMAGE_URL}]
    item["input_fidelity"] = "high"
body = json.dumps({"items": [item]}, ensure_ascii=False).encode("utf-8")
folder = Path.home() / "Downloads" / "8848-images"
folder.mkdir(parents=True, exist_ok=True)
job = hashlib.sha256(API_KEY.encode() + b"\0" + body).hexdigest()[:20]
record = folder / f"{job}.json"
if record.exists():
    state = json.loads(record.read_text())
else:
    state = {"request_id": str(uuid.uuid4())}
    record.write_text(json.dumps(state))

def request(path, data=None):
    headers = {"Authorization": "Bearer " + API_KEY, "User-Agent": "8848-image-example/1.0"}
    if data is not None:
        headers["Content-Type"] = "application/json"
        headers["Idempotency-Key"] = state["request_id"]
    req = urllib.request.Request("https://api.884819.xyz" + path, data=data, headers=headers)
    return urllib.request.urlopen(req, timeout=60)

try:
    if state.get("output") and Path(state["output"]).exists():
        print("这张图已下载：", state["output"])
        raise SystemExit(0)
    if not state.get("batch_id"):
        print("1/4 提交生图任务……", flush=True)
        with request("/v1/images/async", body) as response:
            state["batch_id"] = json.load(response)["batch_id"]
        record.write_text(json.dumps(state))
    print("这一单的 batch_id：", state["batch_id"], flush=True)
    if not state.get("task_id"):
        print("2/4 获取单张图片编号……", flush=True)
        with request("/v1/images/async/" + state["batch_id"]) as response:
            state["task_id"] = json.load(response)["data"][0]["task_id"]
        record.write_text(json.dumps(state))
    print("这张图的 task_id：", state["task_id"], flush=True)
    while True:
        with request("/v1/images/async/tasks/" + state["task_id"]) as response:
            task = json.load(response)
        status = task["status"]
        print("3/4 当前状态：", status, flush=True)
        if status == "succeeded":
            print("4/4 下载图片……", flush=True)
            with request("/v1/images/async/tasks/" + state["task_id"] + "/content") as response:
                kind = response.headers.get("Content-Type", "").split(";")[0].lower()
                suffix = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp"}.get(kind, ".image")
                output = folder / (job + suffix)
                output.write_bytes(response.read())
            state["output"] = str(output)
            record.write_text(json.dumps(state))
            print("完成！图片保存在：", output)
            break
        if status not in ("queued", "running"):
            raise SystemExit("任务已停止：" + json.dumps(task, ensure_ascii=False) + "；请核对，不要重新建单。")
        time.sleep(5)
except urllib.error.HTTPError as error:
    print("接口报错：HTTP", error.code, error.read().decode("utf-8", errors="replace"))
    raise SystemExit("未自动重建任务。修正问题后，以相同参数重新运行可接续本单。")
except (urllib.error.URLError, TimeoutError) as error:
    print("连接中断：", error)
    raise SystemExit("原请求编号已保存在电脑；以相同参数重新运行可继续，不要删除记录。")
PY

图片保存到“下载”文件夹 → 8848-images，自动带上 .png / .jpg / .webp 扩展名，终端会显示完整路径。

详细操作：1、2、3、4、5

1. 打开终端

Mac 按 Command + 空格，搜索“终端”，按回车。Linux 打开系统终端。命令粘在系统终端，不是网页地址栏、聊天输入框或 Python 的 >>> 窗口；此写法不适用于 Windows PowerShell。

需要 Python 3；如果提示找不到 python3，先安装 Python 3。已有 Python 3 无需再安装 requests、jq 等库。

2. 复制完整命令，改两行

点上面的“复制完整命令”，将 API_KEY 引号里的 sk-替换为你的API-Key 换成从主站控制台复制的完整 Key（不是登录密码）；将 PROMPT 三引号里的文字换成你要画的内容，保留引号。

第三行 REFERENCE_IMAGE_URL = "" 保持为空，就是普通文生图。其余地址、模型、任务编号和保存路径不用改。

3. 有参考图时，再填第三行

仍用前面的整段命令，只多填一个完整公网图片地址。顶部三行这样填写，下面其余代码保持不变：

API_KEY = "sk-这里是你自己的完整Key"
PROMPT = """保留参考图中的主体和构图，把背景改为海边日落，写实摄影风格"""
REFERENCE_IMAGE_URL = "这里粘贴你自己的完整公网图片URL"

这三行不是单独运行的命令，要替换进上面的完整命令。参考图须为平台可下载的 PNG / JPEG / WebP，不是本地路径、相册页面、Base64 或 blob 地址；需要登录的图片不能直接用，签名有效期需覆盖排队和生成时间。示例使用 Sunburst 单参考图。

4. 整段粘贴到终端，按回车

从 python3 -I - <<'PY' 一直复制到最后一行 PY。程序自动提交、获取单张编号、每约 5 秒查询，成功后下载。queued 是排队，running 是生成中，继续等即可；不保证固定生成时长。

5. 到“下载”文件夹取图

打开“下载” → 8848-images。图片就是结果，旁边的 JSON 是接续记录，不是图片，也不含 API Key。

连接中断：保留记录，用相同 Key、提示词和参考图地址重新运行，会接续这一单。
相同输入且已下载：提示原图片位置，不重新生成。换提示词或参考图则新建任务、重新计费。
完全相同内容想再生成一张：先确认上一单已结束，再移走对应同名 JSON 记录并重新运行；会新建任务并计费。排查超时时不要移走记录。

一次生成多张：items 里一项就是一张

下面为自行开发批量客户端的 curl 示例，API_KEY 请填你自己的令牌；不属于上面自动单张命令的必做步骤。

export API_KEY='替换为你的API令牌'

例如生成两张，提交两个 item。client_ref 是你自己的图片编号，查询时原样返回，方便对照。以下是新的一单，会另外生成两张并计费：

REQUEST_ID="$(uuidgen)" && \
curl --fail-with-body 'https://api.884819.xyz/v1/images/async' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $REQUEST_ID" \
  -d '{"items":[
    {"client_ref":"cup-001","model":"gpt-image-2.5-sunburst","prompt":"白色背景上的咖啡杯产品摄影","n":1},
    {"client_ref":"bag-002","model":"gpt-image-2.5-sunburst","prompt":"白色背景上的手提包产品摄影","n":1}
  ]}' \
  -o submit.json && jq . submit.json

然后用返回的 batch_id 查询这一单：

BATCH_ID="$(jq -er '.batch_id' submit.json)" && \
curl --fail-with-body "https://api.884819.xyz/v1/images/async/$BATCH_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -o batch.json && jq . batch.json

data 里每一项是一张图，各有自己的 task_id 和状态。下面命令下载本轮查询中所有已成功的图片，以各自 task_id 命名：

jq -r '.data[] | select(.status == "succeeded") | .task_id' batch.json | \
while IFS= read -r TASK_ID; do
  curl --fail "https://api.884819.xyz/v1/images/async/tasks/$TASK_ID/content" \
    -H "Authorization: Bearer $API_KEY" \
    -o "$TASK_ID"
done

每批 1–100 项，每项 n 只能为 1 或省略；50 张就写 50 项，不写 n:50。排队和完成时间各不相同，不要等整单全部完成才下载。程序应按 task_id 记录已下载项，避免反复下载。

同步生图：等待返回 Base64，不用批次号

以下是独立的同步接法，不是前面异步命令的后续步骤。先在同一个终端填入令牌：

export API_KEY='替换为你的API令牌'

然后提交，保持连接等待生成：

curl --fail-with-body 'https://api.884819.xyz/v1/images/generations' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"gpt-image-2.5-sunburst",
    "prompt":"白色背景上的咖啡杯产品摄影",
    "n":1,
    "response_format":"b64_json"
  }' \
  -o sync-result.json

成功响应的图片在 data 中的 b64_json 字段，不是下载链接。执行下面命令解码为 sync-image（需要 Python 3，不会再次生成）：

python3 -I - <<'PY'
import base64
import json
from pathlib import Path
response = json.loads(Path("sync-result.json").read_text())
items = response["data"]
if isinstance(items, dict):
    items = [items]
encoded = next((item["b64_json"] for item in items if item.get("b64_json")), None)
if not encoded:
    raise SystemExit("未找到 Base64 图片，请核对响应和账务，不要自动重新生成")
Path("sync-image").write_bytes(base64.b64decode(encoded, validate=True))
print("已保存 sync-image，按实际图片格式添加 .png / .jpg / .webp 扩展名")
PY

同步参考图：上传本地文件

把当前目录的参考图命名为 reference.png，或替换下面的文件路径：

curl --fail-with-body 'https://api.884819.xyz/v1/images/edits' \
  -H "Authorization: Bearer $API_KEY" \
  --form-string 'model=gpt-image-2.5-sunburst' \
  --form-string 'prompt=保留参考图主体，将光照改为暖色日落' \
  -F 'image=@reference.png' \
  --form-string 'n=1' \
  --form-string 'input_fidelity=high' \
  --form-string 'response_format=b64_json' \
  -o sync-result.json

成功后用上面的 Python 命令解码保存。不要手动设置 multipart 的 Content-Type。

同步 524 或连接断开，不代表生成失败；先查日志与账务，不要直接重发。同步接口没有上述异步批次的幂等保证。

接入时记住这几条

避免重复扣费：异步提交没收到响应，用原请求编号、原正文重试；同用户同键同正文返回原批次（HTTP 200），改正文返回 409。前面的完整命令会保存并复用请求编号；不要删除接续记录或因等得久改走同步重做。
保存进度：正式程序保存请求编号、原正文、batch_id、task_id 和已下载记录；重启后继续查询。查询、下载不会创建新的生图任务。
及时下载：以每张 expires_at（Unix 秒）为准。过期后查询不会延长有效期，正常过期不退款；不要公开令牌或带签名的下载链接。
模型与参数：异步支持 gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst。每项 model、prompt 必填，size、quality 可选且须符合模型支持；异步不要传 response_format、stream。令牌须有对应权限和额度，沿用对应模型、分组的同步计价。
等待时间：服务端可能自动重试，排队另计，不保证固定几分钟完成。不支持本页范围内的回调或客户端取消。

报错	怎么处理
400 / 413	参数或请求体有误，按 error 修正。
401 / 403 / 402	检查令牌、模型权限、账户和令牌额度；签名下载检查链接是否完整有效。
404	编号不存在或不属于当前用户，确认没有把 batch_id、task_id 用反。
409	提交：同请求编号却改了正文；下载：图片还没就绪。看 error.code 区分。
410	图片已过期或不可用，查询不能恢复，不自动重新生成。
429 / 503	稍后再查或重试，遵守 Retry-After，避免密集请求。

既有真实验收记录与本次命令验证

2026-10-14 测试环境的 Sunburst 异步文生图与异步参考图均已有真实付费成功记录：提交 HTTP 202、状态 succeeded、PNG 下载 HTTP 200。不是本次新增生成，也不表示此新脚本已在当前主站实扣运行。

文生图：aib_81b1c068653d42e3a1d29f82 / ait_190756196f7c4850a8f599b2。参考图：aib_30d68c0152604c17ad27668e / ait_2ab9415044ee4247a0c30eb2。旧图片已过期，不可用这些编号重新下载；未公开 API Key 或下载签名。

本次完整命令通过离线验证：文生图、参考图、失败/未知停止、断线接续、提交响应丢失后原键重放、过期下载报错；没有为文档新增付费生成。