Grok Imagine Image 2.0 官方图像生成与编辑

{
  "model": "grok-imagine-image-2.0",
  "prompt": "高级产品摄影，柔和棚拍光线，干净背景",
  "n": 1,
  "aspect_ratio": "1:1",
  "resolution": "2k",
  "quality": "medium"
}

{
  "model": "grok-imagine-image-2.0",
  "prompt": "将白天的天空替换成戏剧性的璀璨星空",
  "n": 1,
  "aspect_ratio": "auto",
  "resolution": "1k",
  "image_urls": [
    "https://cdn.example.com/source.png"
  ]
}

{
  "model": "grok-imagine-image-2.0",
  "prompt": "使用 <IMAGE_0> 作为产品，使用 <IMAGE_1> 作为海报风格",
  "n": 1,
  "aspect_ratio": "4:3",
  "resolution": "2k",
  "image_urls": [
    "https://cdn.example.com/product.png",
    "https://cdn.example.com/style.webp"
  ]
}

POST https://api.apimart.ai/v1/uploads/images
Authorization: Bearer <APIMart_API_KEY>
Content-Type: multipart/form-data

curl --request POST \
  --url https://api.apimart.ai/v1/uploads/images \
  --header 'Authorization: Bearer <token>' \
  --form 'file=@reference.png'

{
  "url": "https://cdn.example.com/image/reference.png",
  "filename": "reference.png",
  "content_type": "image/png",
  "bytes": 123456,
  "created_at": 1786690805
}

GET https://api.apimart.ai/api/pricing/image/quote

GET https://api.apimart.ai/api/pricing/image/quote?model=grok-imagine-image-2.0&resolution=2k&quality=medium&aspect_ratio=16:9&n=2&input_images=3

{
  "success": true,
  "data": {
    "model_name": "grok-imagine-image-2.0",
    "resolution": "2k",
    "aspect_ratio": "16:9",
    "quality": "medium",
    "image_count": 2,
    "unit_price_usd": 0.08,
    "input_images": 3,
    "input_surcharge_usd": 0.03,
    "final_usd": 0.19
  }
}

fetch(url, { credentials: "include" });

{
  "request_id": "req_xxx",
  "error": {
    "message": "具体错误信息",
    "type": "invalid_request_error",
    "param": "",
    "code": "invalid_request_error"
  }
}

type GrokImageModel = "grok-imagine-image-2.0";

type GrokAspectRatio =
  | "1:1" | "3:4" | "4:3" | "9:16" | "16:9"
  | "2:3" | "3:2" | "9:19.5" | "19.5:9"
  | "9:20" | "20:9" | "1:2" | "2:1" | "auto";

interface GrokImageRequest {
  model: GrokImageModel;
  prompt: string;
  n?: number;
  aspect_ratio?: GrokAspectRatio;
  resolution?: "1k" | "2k";
  quality?: "low" | "medium";
  image_urls?: string[];
}

function buildBody(input: GrokImageRequest): GrokImageRequest {
  const prompt = input.prompt.trim();
  if (!prompt) throw new Error("prompt 不能为空");
  if (prompt.length > 8000) throw new Error("prompt 不能超过 8000 个字符");

  const n = input.n ?? 1;
  if (!Number.isInteger(n) || n < 1 || n > 10) {
    throw new Error("n 必须是 1–10 的整数");
  }

  if (input.image_urls && (input.image_urls.length < 1 || input.image_urls.length > 3)) {
    throw new Error("参考图片必须为 1–3 张");
  }

  for (const imageUrl of input.image_urls ?? []) {
    let parsed: URL;
    try {
      parsed = new URL(imageUrl);
    } catch {
      throw new Error("image_urls 必须是公网绝对 HTTP(S) URL");
    }
    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
      throw new Error("image_urls 必须是公网绝对 HTTP(S) URL");
    }
  }

  const body: GrokImageRequest = {
    model: input.model,
    prompt,
    n,
    aspect_ratio: input.aspect_ratio ?? "auto",
    resolution: input.resolution ?? "1k",
  };

  if (!input.image_urls?.length) {
    body.quality = input.quality ?? "medium";
  }

  if (input.image_urls?.length) body.image_urls = input.image_urls;
  return body;
}

export async function submitGrokImageTask(params: {
  apiKey: string;
  request: GrokImageRequest;
  idempotencyKey: string;
  signal?: AbortSignal;
}) {
  const response = await fetch("https://api.apimart.ai/v1/images/generations", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${params.apiKey}`,
      "Content-Type": "application/json",
      Accept: "application/json",
      "Idempotency-Key": params.idempotencyKey,
      "X-APIMart-Response-Version": "2026-07-27",
    },
    body: JSON.stringify(buildBody(params.request)),
    signal: params.signal,
  });

  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw new Error(body.error?.message ?? `图片请求失败（HTTP ${response.status}）`);
  }

  if (body.data?.object !== "generation.task" || !body.data?.id) {
    throw new Error("图片接口未返回有效任务 ID");
  }

  return {
    taskId: body.data.id as string,
    pollUrl: body.data.poll_url as string | undefined,
  };
}