Amux

Create task

最近更新：2026年9月2日

用 openai/gpt-image-2 提交异步任务。不分生成与编辑——带参考图就是编辑。

把 openai/gpt-image-2 的任务提交给 /v1/tasks：立刻拿到 id，生成在后台进行。

这条端点不分生成和编辑 —— 不带 image 就是生成，带了就是编辑。 参数是同一套，所以只有这一页。

下面的参数表是 multipart/form-data 形态——它是超集。不带参考图时， 同样这些字段也可以用 JSON 发。

POSThttps://gateway.amux.ai/v1/tasks

鉴权

header
Authorizationstring必填

Bearer <你的 Amux 密钥> 站内 API Key。

请求

multipart/form-data
modelstring必填

站内模型 ID。

promptstring必填

想要什么。带了参考图时它描述的是「想怎么改」。

imagearray<string>

参考图，可选——不给就是纯生成，给了就是编辑。

最多 16 张、单张 25MB。

image 与 image[] 两种字段名均支持。OpenAI SDK 通常在单图场景使用前者，多图场景使用后者。

maskstring

蒙版，透明处表示要改的区域。三条硬要求：

1. 必须是 PNG 且带 alpha 通道（灰度图要先自己加上）；

2. 尺寸与原图一致，且小于 4MB——这是蒙版自己的上限，

比参考图那个（我们限 25MB）严得多；

3. 多张参考图时它只作用于第一张。

该字段仅在同时提供参考图时生效。单独传入会被忽略，并在 amux.notes 中说明。

ninteger默认 1

出几张。上限 10。

sizestring默认 "1024x1024"

1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 2048x1152 / 3840x2160 / 2160x3840 / auto（默认）， 或任意合法像素串——约束与生成端点相同。

aspect_ratiostring

1:1 / 3:2 / 2:3 / 16:9 / 9:16。size 的另一种写法（Google 生态的说法）， 两者给一个就够；同时给时以 size 为准，并在 amux.notes 里说明。 折成精确像素是有损的，折不出对应档位时会丢掉并记 note——不会替你猜一个尺寸。

image_sizestring

1K / 2K / 4K。和 aspect_ratio 搭配用，规则同上。

quality"low" | "medium" | "high" | "auto"默认 "auto"

low / medium / high / auto。

background"transparent" | "opaque" | "auto"默认 "auto"

transparent / opaque / auto。透明要配 png 或 webp。

output_format"png" | "jpeg" | "webp"默认 "png"

png / jpeg / webp。

output_compressionstring

压缩级别，只对 jpeg / webp 有意义，默认 100。

userstring

端用户标识，用于滥用追踪。

webhook_urlstring

任务到终态时往这里 POST 一份结果。只收 https，且不能指向内网。

moderation"auto" | "low"

审核档位。只在不带参考图时有效——上游的编辑端点没有这个字段，

带了参考图时它会被丢掉并在 notes 里说明。

响应

200response

已经是终态（Prefer: wait 等到了），或者这是一次重放（同一个幂等键）。

和 202 分开是有意的：202 说「我接下了一件事」，而这两种情况都没有接下新的事。

202response

任务已受理，并且预扣已经扣住。拿 id 去取结果。

400response

请求不合法。也包括 stream: true 或 partial_images 大于 0——

这条端点是异步的，同步流式请走 /v1/images/generations。

402response

可用余额不足以覆盖预扣上界。

503response

在途任务已满，稍后重试（响应带 Retry-After）。

拿结果的三种方式

怎么用什么时候合适
轮询GET /v1/tasks/{id}最简单，建议间隔 2–5 秒
回调提交时带 webhook_url不想守着连接
就地等提交时带 Prefer: wait=60想同步拿到，又不想自己轮询

任务生命周期、回调签名与验签示例、幂等键 —— 这些所有模型都一样， 见创建任务。

和厂商兼容端点的区别

/v1/images/*/v1/tasks
生成 / 编辑两条端点一条，按有没有参考图分
交付同步（可流式）异步 + 回调 + 可选就地等
兼容性OpenAI SDK 直接可用我们自己的形状

慢任务用这条：同步那条上任何一环超时（反向代理、网关、客户端默认值） 都会让你拿不到图，而钱已经花了。

错误

错误体形状与 OpenAI 一致，type 取值与重试语义见错误与重试。

cURL
curl https://gateway.amux.ai/v1/tasks \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=openai/gpt-image-2" \
  -F "prompt=Make the fox wear a red scarf" \
  -F "image=@/path/to/image.png" \
  -F "size=1024x1024" \
  -F "webhook_url=https://hooks.example.com/amux"
{
  "id": "task_01M1CG35C16CJ790D00BV1RBVM",
  "status": "queued",
  "model": "openai/gpt-image-2",
  "created_at": "<string>",
  "output": {
    "images": [
      {
        "index": 0,
        "url": "<string>"
      }
    ]
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "cost": "0.2108",
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}