Grok Imagine 2.0 Ext 图层与选区编辑

已完成的 Grok 单图任务 task_id ─┐
                               ├→ segment
上传图片返回的公网图片 URL ──────┘
  → image_id + objects[].mask_rle
  → 前端把 mask 转为 selection_regions
  → region_edit(image_id, prompt, selection_regions)
  → 新图片 URL + 新 image_id

GET https://api.apimart.ai/v1/tasks/{task_id}?language=zh
Authorization: Bearer <APIMART_API_KEY>
Accept: application/json

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

{
  "code": 200,
  "data": {
    "id": "task_...",
    "status": "completed",
    "progress": 100,
    "cost": 0,
    "credits_cost": 0,
    "result": {
      "created": 1786784507,
      "source_task_id": "task_...",
      "image_id": "6b78a7c3-5f9e-4a3d-a928-9e9b42113a3f",
      "image_url": "https://.../source.jpg",
      "cached": false,
      "from_cache": true,
      "cache_status": "hit",
      "objects": [
        {
          "index": 0,
          "name": "red sports car",
          "box_xyxy": [38.1, 689.8, 945.8, 1065.4],
          "score": 0.9765625,
          "mask_size": [1792, 1008],
          "mask_url": "",
          "mask_rle": {
            "size": [1792, 1008],
            "counts": "..."
          }
        }
      ]
    }
  }
}

export interface CocoRLE {
  size: [height: number, width: number];
  counts: string;
}

export interface BinaryMask {
  width: number;
  height: number;
  data: Uint8Array; // data[y * width + x]
}

function decodeCompressedCounts(counts: string): number[] {
  const runs: number[] = [];
  let cursor = 0;

  while (cursor < counts.length) {
    let value = 0;
    let shift = 0;
    let more = true;

    while (more) {
      if (cursor >= counts.length) throw new Error("截断的 COCO RLE counts");
      const current = counts.charCodeAt(cursor++) - 48;
      value |= (current & 0x1f) << shift;
      more = (current & 0x20) !== 0;
      shift += 5;
      if (!more && (current & 0x10) !== 0) value |= -1 << shift;
    }

    if (runs.length > 2) value += runs[runs.length - 2] ?? 0;
    if (value < 0) throw new Error(`非法 COCO RLE run: ${value}`);
    runs.push(value);
  }

  return runs;
}

export function decodeCocoRLE(rle: CocoRLE): BinaryMask {
  const [height, width] = rle.size;
  if (!Number.isInteger(height) || !Number.isInteger(width) || height <= 0 || width <= 0) {
    throw new Error(`非法 mask size: ${JSON.stringify(rle.size)}`);
  }

  const pixelCount = width * height;
  if (!Number.isSafeInteger(pixelCount) || pixelCount > 32_000_000) {
    throw new Error(`mask 像素数超出前端安全上限: ${pixelCount}`);
  }
  if (typeof rle.counts !== "string" || rle.counts.length === 0) {
    throw new Error("缺少 COCO RLE counts");
  }

  const data = new Uint8Array(pixelCount);
  const runs = decodeCompressedCounts(rle.counts);
  let position = 0;
  let foreground = false;

  for (const run of runs) {
    if (position + run > data.length) throw new Error("COCO RLE 超出 mask_size");
    if (foreground) {
      for (let offset = 0; offset < run; offset++) {
        const columnMajorIndex = position + offset;
        const y = columnMajorIndex % height;
        const x = (columnMajorIndex - y) / height;
        data[y * width + x] = 1;
      }
    }
    position += run;
    foreground = !foreground;
  }

  if (position !== data.length) {
    throw new Error(`COCO RLE 只覆盖 ${position}/${data.length} 个像素`);
  }

  return { width, height, data };
}

export interface SelectionBoundary {
  points: number[]; // [x0,y0,x1,y1,...]，坐标范围 0～1
}

export interface SelectionRegion {
  outer: SelectionBoundary;
  holes?: SelectionBoundary[];
}

{
  "code": 200,
  "data": {
    "id": "task_...",
    "status": "completed",
    "progress": 100,
    "cost": 0.016,
    "credits_cost": 0.16,
    "result": {
      "images": [
        {
          "url": ["https://.../result.jpg"],
          "image_ids": ["<NEW_IMAGE_ID>"],
          "items": [
            {
              "url": "https://.../result.jpg",
              "image_id": "<NEW_IMAGE_ID>",
              "source_image_id": "<SOURCE_IMAGE_ID>",
              "role": "region_edit",
              "prompt": "把选中的跑车改成亮红色，保持其他画面不变"
            }
          ],
          "expires_at": 1787040000
        }
      ]
    }
  }
}

interface RegionEditResult {
  images?: Array<{
    url?: string[];
    image_ids?: string[];
    items?: Array<{
      url?: string;
      image_id?: string;
    }>;
  }>;
}

function readRegionEditOutput(result: RegionEditResult): {
  url: string;
  imageId: string;
} {
  const group = result.images?.[0];
  const item = group?.items?.[0];

  if (item?.url && item.image_id && /^https?:\/\//i.test(item.url)) {
    return { url: item.url, imageId: item.image_id };
  }

  if (
    group?.url?.length &&
    group.image_ids?.length === group.url.length &&
    /^https?:\/\//i.test(group.url[0]) &&
    group.image_ids[0]
  ) {
    return { url: group.url[0], imageId: group.image_ids[0] };
  }

  throw new Error("选区编辑完成，但结果缺少对齐的 HTTP(S) URL 或 image_id");
}

const output = readRegionEditOutput(task.data.result);

editor.sourceTaskId = task.data.id;   // 下一次 segment 使用
editor.sourceImageId = output.imageId; // 下一次 region_edit 使用
editor.sourceUrl = output.url;         // 编辑器展示
editor.layers = [];