Grok Imagine API：图片、编辑与视频生成完整指南

Grok Imagine API 不是单一模型，而是覆盖图片生成、图片编辑和视频生成的一组媒体接口。选错模型或把视频任务当成同步请求，是接入时最常见的两个问题。

三个模型分别做什么

模型 ID	用途	典型输入	计费单位
grok-imagine-image	文生图	提示词、尺寸、数量	按张
grok-imagine-edit	图片编辑	提示词、参考图	按张
grok-imagine-video	视频生成	提示词、时长、画幅	按秒

模型是否可用以及实际价格可能随渠道变化。调用前可以先查看 Sublyx 模型广场，生产环境则以控制台展示为准。

图片生成请求

图片生成适合海报草图、商品概念图、社交媒体配图和视觉探索。Sublyx 使用异步提交接口，先返回任务 ID，再查询任务状态。下面是 OpenAI 兼容风格的请求：

curl https://api.sublyx.org/v1/images/generations/async \
  -H "Authorization: Bearer $SUBLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "Editorial product photo of a cobalt blue desk lamp",
    "n": 1,
    "response_format": "b64_json"
  }'

提交成功后保存响应里的 task_id，不要把它当成最终图片响应。任务完成后再从结果中的 URL 或 Base64 数据读取图片。不要直接把完整 Base64 字符串写入日志，它会快速放大日志体积，还可能暴露用户生成内容。

图片编辑请求

编辑模型需要参考图。提示词应明确区分“要改变什么”和“必须保持什么”。例如：“将台灯颜色改成哑光红色，保持构图、阴影和背景不变”比“改成红色”稳定。

curl https://api.sublyx.org/v1/images/edits/async \
  -H "Authorization: Bearer $SUBLYX_API_KEY" \
  -F "model=grok-imagine-edit" \
  -F "prompt=Change the lamp to matte red; keep composition and shadows" \
  -F "image=@lamp.png"

编辑任务的质量上限不仅取决于提示词。参考图分辨率、主体遮挡、压缩噪声和希望修改的区域大小都会影响结果。当前接口限制参考图为 PNG、JPG 或 WEBP，建议控制在 5MB 以内。

提交任务后如何轮询

图片生成和编辑共用任务查询端点：GET /v1/images/tasks/:task_id。建议首次等待约 10 秒，之后每 4 秒查询一次，并设置总超时；状态为 completed 时读取结果，failed 或 cancelled 时停止重试。

const taskId = submit.task_id;
const deadline = Date.now() + 6 * 60 * 1000;

while (Date.now() < deadline) {
  const response = await fetch(
    `https://api.sublyx.org/v1/images/tasks/${encodeURIComponent(taskId)}`,
    { headers: { Authorization: `Bearer ${process.env.SUBLYX_API_KEY}` } }
  );
  const task = await response.json();

  if (task.status === "completed") {
    console.log(task.result || task.image_url);
    break;
  }
  if (["failed", "cancelled"].includes(task.status)) {
    throw new Error(task.error?.message || task.message || task.status);
  }
  await new Promise((resolve) => setTimeout(resolve, 4000));
}

视频生成与轮询

视频生成通常耗时更长，不适合让一次 HTTP 请求一直等待。当前站内已验证的是图片异步接口；视频端点、返回字段和轮询方式应以控制台显示的最新文档为准，发布前不要把未经验证的 URL 当作稳定公共 API。

const submit = await fetch("https://api.sublyx.org/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SUBLYX_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "grok-imagine-video",
    prompt: "A slow dolly shot through a rainy neon alley",
    duration: 6,
    aspect_ratio: "16:9",
    resolution: "720p"
  })
});

const { request_id } = await submit.json();

如果你的账户已启用视频接口，轮询间隔建议从 2 至 5 秒起步，并设置总超时时间。遇到临时错误时使用指数退避，不要每 100 毫秒查询一次。任务完成后，应把结果下载到自己的对象存储，避免长期依赖临时 URL。图片任务遇到 429 时，可参考AI API 429 错误排查指南；生产环境的路由、限流和成本治理可参考AI API 聚合网关指南。

成本怎么估算

图片成本等于生成张数乘以每张单价。视频成本通常等于生成秒数乘以每秒单价。还要考虑重试、失败任务是否计费、为了挑选结果一次生成多个候选等业务因素。

月成本 ≈ 日请求量 × 平均媒体单位 × 单价 × 30 × 重试系数

例如每天生成 100 段 6 秒视频，单价为每秒 0.05 美元，忽略重试时月度参考成本为 900 美元。上线前应设置用户配额、每日预算和异常增长告警。

常见问题

返回 401 或 403

检查 API Key、请求域名、模型权限和账户余额。不要在浏览器公开代码里硬编码 Key。

任务长时间 processing

确认轮询端点和任务 ID 正确，同时为单个任务设置最大等待时间。超过阈值后保留任务 ID，避免盲目重复提交并产生双倍费用。

图片编辑没有遵循参考图

降低一次修改的目标数量，明确列出需要保持的元素，并尝试更清晰、压缩更少的输入图。