2026/10/09

MAI Image 2.6 API 가이드: 생성·편집·작업 조회

MAI Image 2.6으로 생성 요청을 보내고 참조 이미지를 순서대로 추가합니다. 유효한 크기 선택, 비동기 작업 조회, 예상 비용과 최종 결과 처리까지 reAPI 연동 흐름을 설명합니다.

MAI Image 2.6을 처음 연동할 때는 애플리케이션이 어떤 서비스의 계약을 따를지 먼저 결정해야 합니다. Microsoft는 Foundry를 통한 생성과 편집을 문서화합니다. reAPI에서는 두 작업 모두 이미지 생성 엔드포인트를 사용합니다. 편집할 때 참조 URL을 추가한 뒤 반환된 작업 ID를 조회합니다. 서비스마다 모델 이름은 비슷하지만 인증, 요청 본문, 응답은 서로 바꿔 사용할 수 없습니다.^[1]

이 가이드는 mai-image-2.6의 reAPI 계약을 따릅니다. 참조 이미지 처리나 자동 구도 설정을 추가하기 전에 텍스트 전용 요청 하나부터 시작합니다. 요청이 실패했을 때 점검할 연동 범위를 작게 유지할 수 있습니다. 구현할 때 전체 매개변수 문서를 함께 참고합니다. MAI Image 2.6 플레이그라운드에는 같은 설정과 현재 예상 비용이 제공됩니다.^[2]

핵심 안내

비어 있지 않은 프롬프트와 함께 mai-image-2.6을 images 엔드포인트에 제출합니다. 요청 하나가 이미지 한 장을 생성합니다.^[2]
비율과 1K 또는 2K를 사용하거나 유효한 너비·높이 쌍을 지정합니다. 이 엔드포인트는 4K를 지원하지 않습니다.^[2]
참조 이미지 편집에는 순서가 지정된 공개 이미지 URL을 최대 5개 제공합니다. 참조 이미지가 있으면 출력 크기는 모델이 선택합니다.^[2]
반환된 작업 ID를 저장하고 completed 또는 failed가 될 때까지 조회합니다. 제출 응답 자체에는 완성된 이미지가 없습니다.^[2]
표시된 비용은 예상 금액으로 다룹니다. 완료 시 예약 금액을 정산하며 ?include=billing으로 정확한 청구 정보를 확인할 수 있습니다.^[2]

첫 MAI Image 2.6 요청 보내기

reAPI 키를 생성하고 서버 환경에 REAPI_API_KEY로 저장합니다. 요청에는 모델과 비어 있지 않은 프롬프트가 필요합니다. 아래 예제는 의도한 캔버스를 확인하기 쉽도록 픽셀 크기를 직접 지정한 정사각형 이미지를 요청합니다. 예제 요청이며 생성되는 모든 사물이 기획 내용과 완벽히 일치한다는 보장은 아닙니다.

curl https://reapi.ai/api/v1/images/generations \
  -H "Authorization: Bearer $REAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mai-image-2.6",
    "prompt": "A matte ivory ceramic teapot on a pale blue table, soft daylight, product photography.",
    "width": 1024,
    "height": 1024,
    "n": 1
  }'

API ID에는 6 앞에 점이 있습니다. 모델 페이지 URL은 /models/mai-image-2-6을 사용합니다. 이 하이픈 슬러그를 요청에 복사하면 다른 문자열이 됩니다. 제출에 성공하면 반환된 작업 id를 즉시 저장합니다. 결과 조회, 실패 식별, 클라이언트 연결 종료 후 복구에 사용합니다. 요청 하나가 이미지 한 장을 생성하며 n을 늘려도 지원되는 배치 요청이 되지 않습니다.^[2]

키를 브라우저 코드에 넣지 않습니다. 프런트엔드는 사용자의 기획 내용을 백엔드에 전달하고, 백엔드가 Bearer 토큰을 추가해 요청을 제출할 수 있습니다. 접근 설계에 따라 애플리케이션의 작업 식별자 또는 작업 ID를 프런트엔드에 반환합니다. 키를 쿼리 문자열, 스크린샷, 복사한 오류 보고서에 포함하지 않습니다.

이미 제출한 작업 조회하기

제출 성공은 접수 확인이며 완성된 이미지가 아닙니다. 작업이 completed 또는 failed가 될 때까지 GET /api/v1/tasks/:id를 반복 조회합니다. 완료된 작업은 output.image_urls에 이미지를 제공하고 실패한 작업은 error를 제공합니다. 기존 usage.credits 값은 정수 크레딧으로 표시됩니다. 정확한 회계를 위해 ?include=billing으로 조회하여 billing.credits_exact와 billing.cost_usd, 그리고 제공되는 경우 실제 청구와 부족 금액 관련 근거를 확인합니다. 원래 작업을 조회해도 새로운 생성 요청이 제출되지 않습니다.^[2]

const taskId = submittedTask.id;
const headers = { Authorization: `Bearer ${process.env.REAPI_API_KEY}` };
const deadline = Date.now() + 5 * 60 * 1000;

while (Date.now() < deadline) {
  const response = await fetch(
    `https://reapi.ai/api/v1/tasks/${encodeURIComponent(taskId)}`,
    { headers },
  );
  if (!response.ok) {
    throw new Error(`Task lookup failed: HTTP ${response.status}; task ${taskId}`);
  }
  const task = await response.json();
  if (task.status === 'completed') {
    console.log(task.output.image_urls, task.usage);
    break;
  }
  if (task.status === 'failed') {
    throw new Error(JSON.stringify({ taskId, error: task.error }));
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

여기서 submittedTask는 성공한 제출 응답을 파싱한 값입니다. 5분 제한은 애플리케이션 예제이며 지연 시간 보장이 아닙니다. 시간이 지나면 taskId를 보관하고 애플리케이션이 대기를 종료했음을 표시합니다. 작업이 실패를 보고하지 않았다면 생성 자체를 실패로 표시하지 않습니다. 운영용 클라이언트에서는 루프가 끝난 뒤 별도의 시간 초과 상태를 반환하고 기존 작업의 상태를 다시 확인할 수 있게 합니다.

제출 후 네트워크 오류가 발생하면 다른 불확실성도 생깁니다. 연결이 끊기기 전에 서버가 요청을 수락했을 수 있습니다. 모든 POST를 자동으로 반복하면 추가 유료 작업이 생성될 수 있습니다. 제출과 조회를 분리하고 선택적 UI 처리를 하기 전에 반환된 ID를 저장합니다.

엔드포인트가 허용하는 크기 선택하기

텍스트 전용 MAI Image 2.6 요청에는 비율과 해상도 단계를 사용하거나 픽셀 크기를 직접 지정합니다. 엔드포인트는 1K와 2K를 허용하며 4K는 허용하지 않습니다. 명시적으로 지정한 각 변은 최소 768픽셀이어야 하고 총면적은 2,359,296픽셀을 초과할 수 없습니다. 비율은 양의 정수로 지정하며 1:4부터 4:1까지 지원합니다.^[2]

요청	의미
`size: "16:9", resolution: "2K"`	선택한 해상도 단계의 가로형 구도
`size: "1536x1024"`	직접 지정한 픽셀 크기
`width: 1024, height: 1024`	너비·높이 쌍으로 지정한 캔버스
`size: "auto"`	모델에 구도 추론 요청
`width: 2048, height: 2048`	유효하지 않음: 픽셀 면적 초과

너비·높이 쌍은 size의 픽셀 크기보다 우선하며, 픽셀 크기는 비율과 해상도 조합보다 우선합니다. 가능하면 하나의 명확한 크기 지정 방식만 사용합니다. 예를 들어 width: 1024, height: 1024와 size: "16:9"를 함께 보내면 문서의 우선순위로 처리되더라도 서로 모순된 의도를 전달합니다. 자체 입력 폼에서 이런 혼란을 방지할 수 있습니다.

크기는 32의 배수로 내림 처리됩니다. 따라서 1000 × 1000 요청은 크기 규칙상 992 × 992에 해당합니다. 정확한 납품 크기가 필요한 레이아웃이라면 요청에 유효한 배수를 사용하고 다운로드한 파일의 크기를 확인합니다. 이후 자르기나 크기 변경은 애플리케이션의 별도 단계로 다룹니다.^[2]

생성에서 참조 이미지 편집으로 전환하기

MAI Image 2.6 요청에 image_urls를 추가해 시각적 참조를 제공합니다. reAPI 엔드포인트는 공개 HTTP(S) 이미지 URL을 최대 5개 허용합니다. 프롬프트는 계속 필수입니다. 참조 이미지 순서를 유지하고 어떤 이미지가 장면, 피사체, 스타일을 제공하는지 설명합니다.^[2]

{
  "model": "mai-image-2.6",
  "prompt": "Use the first image as the room and the second as the chair. Replace the chair beside the window. Preserve the floor, window, and camera view.",
  "image_urls": [
    "https://example.com/room.jpg",
    "https://example.com/chair.jpg"
  ],
  "web_grounding": false
}

예제 URL은 접근 가능한 이미지 파일로 바꿔야 합니다. JPEG 또는 PNG를 권장합니다. 로그인해야 열리는 URL은 이 요청의 참조 URL로 적절하지 않습니다. URL이 HTML 뷰어나 만료된 접근 페이지가 아니라 의도한 이미지 바이트를 반환하는지 확인합니다.

참조 이미지 편집에는 다른 크기 규칙이 적용됩니다. 모델이 출력 크기를 선택하며 size, resolution, width, height는 그 크기를 제어하지 않습니다. 기존 텍스트 전용 요청에 참조 이미지를 추가하면 시각적 컨텍스트만 바뀌는 것이 아닙니다. 반환되는 캔버스에 대해 애플리케이션이 보장할 수 있는 내용도 달라집니다.^[2]

“방을 그대로 유지”하라는 지시를 픽셀이 동일하게 보존된다는 보장으로 해석하지 않습니다. 편집된 사물, 가까운 가장자리, 반사, 유지해야 할 요소를 점검합니다. 제품 작업에서는 로고, 라벨, 물리적 비율을 별도로 확인합니다. 이는 권장 검수 항목이며 이 가이드가 해당 작업의 모델 정확도를 실측했다는 주장이 아닙니다.

자동 구도와 웹 그라운딩을 의도에 맞게 사용하기

auto_aspect_ratio: true는 MAI Image 2.6이 프롬프트에서 구도를 추론하도록 요청하며 size: "auto"도 같은 역할을 합니다. 구도를 탐색할 때 유용하지만 다음 단계에 고정 캔버스가 필요하다면 덜 적합합니다. 자동 선택을 사용하면 완료 전 출력 픽셀 수도 확정되지 않습니다.

web_grounding은 별도의 불리언 설정이며 기본값은 false입니다. Microsoft는 웹 컨텍스트를 모델의 창작 입력 중 하나로 설명하지만, 설정을 켜도 표현된 모든 라벨이나 사실에 신뢰성이 보장되지는 않습니다. 완성된 결과물에 중요한 정보를 검토합니다.^[3]

어느 설정도 명확한 프롬프트를 대신하지 않습니다. 피사체, 구도, 소재, 의도한 변경 사항을 먼저 설명합니다. 그런 뒤 기획에 도움이 되는 설정을 활성화합니다. 제출 값을 기록하면 프롬프트 수정과 설정 변경을 구분할 수 있습니다.

재시도 자동화 전에 예상 비용 이해하기

MAI Image 2.6 비용은 입력과 생성된 픽셀 수에 영향을 받습니다. reAPI는 제출 시 예상 금액을 예약하고 완료 후 비용을 정산합니다. 최종 금액은 더 낮거나 높을 수 있습니다. 참조 이미지와 모델이 선택하는 크기 때문에 예상 비용을 이미지당 고정 가격으로 볼 수 없습니다.^[2]

보낼 요청에 대해 모델 페이지의 현재 예상 비용을 확인합니다. 별도의 비용 및 Flash 가이드는 정사각형 이미지 예상 비용, 참조 이미지 편집, 가로로 긴 이미지가 서로 다른 예산 사례인 이유를 설명합니다. 이 글은 예제 코드에 요율을 고정하지 않습니다.

실패한 생성은 작업 계약에 따라 환불됩니다. 마음에 들지 않는 완성 이미지도 생성이 완료된 결과입니다. 따라서 창작을 위한 반복 시도는 별도 작업으로 예산에 반영합니다. 채택한 결과와 필요한 시도 수를 기록하면 단일 제출 가격뿐 아니라 실제로 사용할 수 있는 결과물의 비용을 비교할 수 있습니다.

Microsoft Learn. Microsoft Foundry에서 MAI 이미지 모델 배포 및 사용. 2026년 10월 9일 조회: learn.microsoft.com/azure/foundry/foundry-models/how-to/use-foundry-models-mai-image.
reAPI. MAI Image 2.6 요청, 크기 설정, 작업 조회, 청구 계약. 2026년 10월 9일 검토: reapi.ai/docs/mai-image-2-6.
Microsoft AI. MAI-Image-2.6. 2026년 10월 9일 조회: microsoft.ai/models/mai-image-2-6.