Create task

把 x-ai/grok-imagine-image-2.0 的任务提交给 /v1/tasks：立刻拿到 id，生成在后台进行。

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

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

鉴权

header

Authorizationstring必填

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

请求

multipart/form-data

modelstring必填

站内模型 ID，可带 :供应商 后缀锁定供应商。

promptstring必填

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

imagearray<string>

参考图，可选——不给就是纯生成，给了就是编辑。image 与 image[] 两种字段名均支持。

最多 5 张、单张 25 MiB，且编码后的总大小不超过 48 MB。

ninteger默认 1

出几张（1–10，默认 1）。按张计费，预扣也按张乘。

aspect_ratio"1:1" | "4:3" | "3:4" | "3:2" | "2:3" | "16:9" | "9:16" | "2:1" | "1:2" | "21:9" | "5:2" | "19.5:9" | "9:19.5" | "20:9" | "9:20" | "auto"默认 "1:1"

出图比例，默认 1:1。与上游支持的取值完全一致，共十六个：

1:1 4:3 3:4 3:2 2:3 16:9 9:16 2:1 1:2 21:9 5:2 19.5:9 9:19.5 20:9 9:20 auto

比例只改变产物形状，不改变计费档位——十六个实测同价。

取值域之外的比例会被丢弃并在 amux.notes 中说明，不会替你猜一个。

image_size"1K" | "2K"默认 "1K"

分辨率档。1K（默认）或 2K。不支持 4K。

它同时决定产物格式：1K 出 JPEG，2K 出 PNG。实际格式以响应中的地址后缀为准。

未提供时按 1K 发出——档位会显式写进上游请求，不依赖上游默认值。

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

渲染质量。low（默认）/ medium / auto。不支持 high，该模型的上游会明确拒绝这个取值。

auto 等同于 low。未提供时按 low 发出——档位会显式写进上游请求，不依赖上游默认值（上游的默认档在生成与编辑两条端点上并不一致）。

moderation"auto" | "low" | "high"默认 "auto"

内容审核强度。auto（默认）/ low / high。

userstring

端用户标识，用于滥用追踪。不需要就整个别传。

webhook_urlstring

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

响应

200response

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

202response

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

400response

请求不合法。也包括 stream 与 partial_images——这条端点是异步的，而这两个模型本来也不支持流式。

402response

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

503response

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

拿结果的三种方式#

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

和兼容端点的区别#

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

参考图#

字段名 image 或 image[] 都收（官方 SDK 单图发前者、多图发后者）。参考图可选——不给就是纯生成，给了就是编辑。

三条限制，任何一条超了都返回 400，不会静默丢图：

1. 最多 5 张——这是上游对这个模型的硬限制；
2. 单张不超过 25 MiB；
3. 编码后总大小不超过 48 MB。

参考图按张计入成本，与出图张数（n）无关：出两张图、给一张参考图， 参考图仍然只算一张。

⚠️ 不支持蒙版（mask），上游的编辑端点没有这个概念。传了会被丢弃并在 amux.notes 中说明。

⚠️ 参考图必须以文件形式上传，不支持传 URL。

尺寸与格式#

尺寸由两个参数表达：aspect_ratio（比例）与 image_size（分辨率档）。 这个模型不接受 size（精确像素串），传了会被丢弃并在 amux.notes 中说明。

其余比例按同一档位缩放，逐个取值见下一节。不支持 4K。

比例只改变产物形状，不改变计费档位；分辨率档会改变。

⚠️ 产物格式跟着 image_size 走，不可指定——output_format 与 output_compression 在这个模型上都不生效。以响应地址的后缀为准。

比例#

出图比例，默认 1:1。与上游支持的取值完全一致，共十六个：

比例只改变产物形状，不改变计费档位——十六个比例实测同价。

取值域之外的比例会被丢弃并在 amux.notes 中说明，不会替你猜一个。

quality#

low（默认）/ medium / auto。不支持 high——上游会明确拒绝该取值。 auto 等同于 low。

quality 与 image_size 共同决定计费档位，四种组合各有各的价， 详见模型详情页的价格表。

⚠️ 未提供时我们会显式发出 low，而不是交给上游去挑默认值。 上游在生成端点与编辑端点上的默认档并不一致，显式发出才能保证 「按哪一档计费」与「上游按哪一档收费」始终是同一档。

不支持的参数#

传了不会报错，会被丢弃并在 amux.notes 里说明——所以拿到图之后如果效果不对， 先看一眼 notes。

⚠️ style 是例外：它被丢弃时不会出现在 amux.notes 里。 上表其余参数都在这个模型的参数矩阵里标着「不支持」，所以丢弃时有据可报； 而 style 不是站内建模过的参数，请求解析时就不会保留它。 换句话说，传了 style 没有任何反馈，请按它不存在来写代码。

错误#

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

curl https://gateway.amux.ai/v1/tasks \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -F "model=x-ai/grok-imagine-image-2.0" \
  -F "prompt=Make the fox wear a red scarf" \
  -F "image=@/path/to/image.png" \
  -F "image_size=1K" \
  -F "webhook_url=https://hooks.example.com/amux"

{
  "id": "task_01M1CG35C16CJ790D00BV1RBVM",
  "status": "queued",
  "model": "x-ai/grok-imagine-image-2.0",
  "created_at": "<string>",
  "output": {
    "images": [
      {
        "index": 0,
        "url": "<string>"
      }
    ]
  },
  "usage": {
    "output_images": 0,
    "input_images": 0
  },
  "cost": "0.0500",
  "error": {
    "message": "<string>",
    "code": "<string>"
  }
}