异步生图

先提交生图任务，取得任务 ID；再查询任务状态，成功后下载图片，也可通过 Webhook 接收完成通知。全程通过 API 操作，无需登录网站取图。所有接口以 https://api.yomiapi.com 为根地址，下面的路径已包含 /v1，不要重复拼接。

使用具有对应模型权限、可用线路和足够余额的 API Key，保存在你的服务器中。提交请求使用以下请求头；查询与下载也须携带有效 Bearer Key。建议沿用提交时的 Key，同账号其他有效 Key 也可用于取图。

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

异步任务不等于 stream: true。仅支持同步生图的软件需要增加“提交、查询、取图”逻辑，不能只换接口地址。

支持的模型与分辨率

普通 gpt-image-2.5 继续使用原有同步接口，不支持本文的异步接口及 Webhook。

GPT：size 的 1K 示例为 1024x1024，2K 为 2048x2048，4K 为 3840x2160 或 2160x3840；不支持 4096x4096。自定义尺寸最大单边 3840，宽高须为 16 的倍数，长宽比不超过 3:1，总像素为 655360–8294400。

Gemini：imageSize 使用大写 1K、2K、4K，Lite 仅支持 1K；aspectRatio 示例为 1:1。档位不代表不同画幅具有相同宽高像素。

Grok：resolution 使用小写 1k、2k；文生图仅支持正方形，aspect_ratio 为 1:1。参考图编辑不传 aspect_ratio。GPT、Gemini、Grok 每次任务输出一张图片；参考图是输入，不计作输出张数。

Midjourney：当前为 1K，size 可省略或填写 1024x1024；n: 1 表示一次任务，目前通常返回四张图，按一次任务计费。图片数量以实际返回的数组为准。

1. 提交任务

以下请求均明确使用 1K。模型须已向账号开通；Gemini 的模型 ID 写在请求路径中。

GPT Image

POST /v1/async/images/generations

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A cat wearing a top hat",
  "size": "1024x1024",
  "n": 1
}

GPT 参考图编辑

POST /v1/async/images/edits

{
  "model": "gpt-image-2.5-flare",
  "prompt": "Keep the product, change the background to white",
  "images": [
    "https://example.com/product.png"
  ],
  "size": "1024x1024",
  "n": 1
}

image 或 images 选一个字段，值须为非空数组；元素可为 HTTP/HTTPS URL、data:image/png;base64,...、纯 Base64，或 {"url":"https://..."} / {"image_url":"https://..."}。参考图数量与 n: 1 的输出张数无关。此异步入口仅接收 JSON，不接收二进制 multipart；JSON mask 暂不支持。请求体仍受平台大小限制。

Gemini

POST /v1/async/gemini/models/gemini-3.1-flash-image-preview:asyncGenerateContent

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "A cat wearing a top hat"
        }
      ]
    }
  ],
  "generationConfig": {
    "imageConfig": {
      "imageSize": "1K",
      "aspectRatio": "1:1"
    }
  }
}

参考图仍使用同一 Gemini 异步入口，在 contents[].parts[] 中加入 inlineData（含 mimeType 和 Base64 data）或 fileData（含 fileUri）；也兼容 inline_data / file_data、mime_type / file_uri。例如把以下部分加入上述 parts 数组：

{"fileData":{"mimeType":"image/png","fileUri":"https://example.com/reference.png"}}

Grok

POST /v1/async/grok/images/generations

{
  "model": "grok-imagine-image-quality",
  "prompt": "A cat wearing a top hat",
  "resolution": "1k",
  "aspect_ratio": "1:1",
  "n": 1
}

Grok 参考图编辑

POST /v1/async/grok/images/edits

{
  "model": "grok-imagine-image-quality",
  "prompt": "Keep the product, change the background to white",
  "images": [
    {
      "type": "image_url",
      "url": "https://example.com/product.png"
    }
  ],
  "resolution": "1k",
  "n": 1
}

image 传单个参考图对象；或用 images 数组传 1～3 个此类对象，两者不能同时传入。对象格式为 {"type":"image_url","url":"https://..."} 参考图对象；只支持 URL。resolution 为 1k 或 2k，n 为 1，不要在编辑请求中传 aspect_ratio。

Midjourney

POST /v1/async/midjourney/submit/imagine

{
  "model": "midjourney",
  "prompt": "A cat wearing a top hat",
  "size": "1024x1024",
  "n": 1
}

可直接执行的提交示例

以下 curl 为 Bash/zsh 语法。先在环境变量中配置 YOMI_API_KEY，再执行提交；后面的查询、下载示例使用同一个变量。

curl --fail-with-body 'https://api.yomiapi.com/v1/async/images/generations' \
  -H "Authorization: Bearer $YOMI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-image-2.5-flare","prompt":"A cat wearing a top hat","size":"1024x1024","n":1}'

提交响应

提交成功当前返回 HTTP 200，仅表示受理成功，不代表图片已生成。GPT、Gemini、Grok 返回 taskID；Midjourney 返回 task_id。保存任务编号、模型和接口类别，后续查询不会回传模型字段。以下响应仅展示关键字段，编号与时间为示例；createdAt 为 Unix 秒。

{
  "taskID": "task_EXAMPLE",
  "status": "queued",
  "createdAt": 1790200000
}

{
  "task_id": "task_EXAMPLE",
  "status": "SUBMITTED"
}

2. 查询任务

将 task_EXAMPLE 替换为提交返回的编号，使用有效 API Key，每隔 5～10 秒查询一次；成功或失败后停止轮询。

curl --fail-with-body 'https://api.yomiapi.com/v1/async/image-tasks/task_EXAMPLE' \
  -H "Authorization: Bearer $YOMI_API_KEY"

GPT、Gemini、Grok 成功时读取 resultImages；Midjourney 读取 images。遍历实际返回的数组，不自行生成图片编号，也不要仅靠进度百分比判断成功。

{
  "taskID": "task_EXAMPLE",
  "status": "success",
  "createdAt": 1790200000,
  "resultImages": [
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-0/content"
    }
  ]
}

{
  "task_id": "task_EXAMPLE",
  "status": "SUCCESS",
  "images": [
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-1/content"
    },
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-2/content"
    },
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-3/content"
    },
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-4/content"
    }
  ]
}

失败与暂不确定状态

失败后停止查询。前三类模型通过 statusMessage 返回说明；Midjourney 使用 error。

{
  "taskID": "task_EXAMPLE",
  "status": "failed",
  "createdAt": 1790200000,
  "statusMessage": "Image generation failed"
}

{
  "task_id": "task_EXAMPLE",
  "status": "FAILURE",
  "images": [],
  "error": "Midjourney generation failed"
}

unknown / UNKNOWN 表示当前状态暂不确定，不代表任务失败。保留任务编号，降低频率继续查询；持续异常时联系支持。查询暂时断网可退避重试，客户端等待超时也不代表任务已取消。

提交 POST 若发生网络超时，可能已经受理，请勿盲目重复提交，以免重复生成和收费。拿到任务编号时优先查询；没有编号且无法确认时，保留请求时间并联系支持。提交接口不承诺幂等去重。

3. 下载图片

当前返回本站鉴权下载地址。使用查询结果实际返回的 URL，相对路径前加 https://api.yomiapi.com，并附带同账号有效 Bearer Key。成功后再执行下载：

curl --fail 'https://api.yomiapi.com/v1/tasks/task_EXAMPLE/artifacts/image-0/content' \
  -H "Authorization: Bearer $YOMI_API_KEY" \
  -D image-headers.txt \
  -o image.bin

下载响应是图片二进制，格式以响应头 Content-Type 为准，再选择 PNG/JPEG/WebP 等对应扩展名。不是 HTML 或 b64_json；如需 Base64，由客户后端下载后自行编码。不要向其他域名发送 Yomi API Key。

图片链接不承诺永久有效，成功后请及时下载到自己的存储；Webhook 不会延长图片有效期。浏览器普通图片标签无法直接附加 Bearer 请求头，建议由客户后端下载或代理展示。

4. 可选：任务完成通知

在提交时同时加入以下两个头；不配置时使用查询接口，配置后仍可主动查询。

X-Async-Callback-URL: https://your-domain.example/image-completed
X-Async-Callback-Secret: YOUR_CALLBACK_SECRET

回调地址须为默认 443 端口的公网 HTTPS 地址。密钥为 16～256 个可打印 ASCII 字符，建议使用至少 32 字节随机值的十六进制编码，不能复用 Yomi API Key。任务结束后向该地址 POST JSON；四类接口的通知统一使用小写状态，成功示例：

{
  "event": "image.task.completed",
  "task_id": "task_EXAMPLE",
  "model": "gpt-image-2.5-flare",
  "status": "success",
  "created_at": 1790200000,
  "started_at": 1790200005,
  "finished_at": 1790200045,
  "result_images": [
    {
      "url": "/v1/tasks/task_EXAMPLE/artifacts/image-0/content"
    }
  ]
}

model 为提交请求时填写的模型名称，时间为 Unix 秒；没有记录的开始、结束时间会省略。失败通知为 status: "failed"，含 error: "Image generation failed"，不含 result_images。Midjourney 通知的图片数组包含实际输出的全部图片。

验签与防重放

X-Async-Task-Id: task_EXAMPLE
X-Async-Timestamp: 1790200045
X-Async-Signature: sha256=<64 hex characters>

签名为 sha256= 加上 HMAC-SHA256(secret, timestamp + "." + rawBody) 的十六进制结果。rawBody 必须是原始请求体字节，不能先解析 JSON 再序列化。使用恒定时间比较，并校验时间戳（例如 5 分钟容差），保持服务器时钟准确。Python 示例：

import hashlib
import hmac
import time

def verify_callback(raw_body: bytes, timestamp: str,
                    signature: str, secret: str) -> bool:
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
        message = timestamp.encode("ascii") + b"." + raw_body
        expected = "sha256=" + hmac.new(
            secret.encode("ascii"), message, hashlib.sha256
        ).hexdigest()
        return hmac.compare_digest(expected, signature)
    except (ValueError, TypeError, UnicodeError):
        return False

重试、去重与补查

验签通过后，按 task_id 去重，将事件可靠保存后快速返回 2xx，图片下载在独立的后台任务中处理。重复通知也应返回 2xx，避免重复执行业务。图片仍须用 API Key 下载。

连接失败、非 2xx 或 10 秒超时会触发重试：总共最多 5 次投递，重试等待约 15/60/300/900 秒，加调度延迟；任务完成超过 24 小时后不再投递。重试只重发通知，不重新生图。

即使启用通知，也应主动补查长时间未收到通知的任务。Webhook 不保证恰好投递一次，不含价格、余额或 Token 用量，也不作为账务结算凭证。

5. 费用与记录

价格按所选模型、分辨率及账号适用价目表确定，请在模型服务中查看或使用双方确认的报价。Midjourney 一次任务通常返回四张图，按一次任务收费，不按四次任务计算。

控制台“任务记录”查看异步任务进度和结果；同步与异步费用统一在“用量统计”及其详细记录导出中对账。