이미지 생성

호출별 model 재정의는 해당 제공자/모델만 시도하며, 구성된 기본/폴백 또는 자동 감지된 제공자로 계속 진행하지 않습니다.

OpenClaw가 해당 제공자를 실제로 인증할 수 있는 경우에만 제공자 기본값이 후보 목록에 추가됩니다. 명시적인 model, primary, fallbacks 항목만 사용하려면 agents.defaults.mediaGenerationAutoProviderFallback: false로 설정합니다.

이미지 백엔드가 느린 경우 agents.defaults.imageGenerationModel.timeoutMs를 설정합니다. 호출별 timeoutMs 도구 매개변수는 구성된 기본값보다 우선하고, 구성된 기본값은 Plugin에서 작성한 제공자 기본값보다 우선합니다. Google 및 OpenRouter 호스팅 이미지 제공자의 기본값은 180초이고, Microsoft Foundry MAI, xAI 및 Azure OpenAI 이미지 생성의 기본값은 600초입니다. Codex 동적 도구 호출은 image_generate 브리지 기본값으로 120초를 사용하며, 구성된 경우 동일한 시간 제한 예산을 준수하되 OpenClaw의 동적 도구 브리지 최댓값인 600000ms로 제한됩니다.

action: "list"를 사용하여 현재 등록된 제공자, 각 제공자의 기본 모델, 인증 환경 변수 힌트를 확인합니다.

OpenAI 이미지 생성의 기본값은 openai/gpt-image-2입니다. openai OAuth 프로필이 구성되어 있으면 OpenClaw는 Codex 구독 채팅 모델에서 사용하는 것과 동일한 OAuth 프로필을 재사용하고 Codex Responses 백엔드를 통해 이미지 요청을 전송합니다. https://chatgpt.com/backend-api 같은 레거시 Codex 기본 URL은 이미지 요청 시 https://chatgpt.com/backend-api/codex로 정규화됩니다. OpenClaw는 해당 요청에서 OPENAI_API_KEY로 자동 폴백하지 않습니다. OpenAI Images API로 직접 라우팅하려면 API 키, 사용자 지정 기본 URL 또는 Azure 엔드포인트를 사용하여 models.providers.openai를 명시적으로 구성합니다.

openai/gpt-image-1.5, openai/gpt-image-1 및 openai/gpt-image-1-mini 모델도 명시적으로 선택할 수 있습니다. 투명 배경 PNG/WebP 출력에는 gpt-image-1.5를 사용합니다. 현재 gpt-image-2 API는 background: "transparent"를 거부합니다.

gpt-image-2는 동일한 image_generate 도구를 통한 텍스트 기반 이미지 생성과 참조 이미지 편집을 모두 지원합니다. OpenClaw는 prompt, count, size, quality, outputFormat 및 참조 이미지를 OpenAI로 전달합니다. OpenAI는 aspectRatio 또는 resolution을 직접 수신하지 않습니다. 가능한 경우 OpenClaw가 이를 지원되는 size로 매핑하며, 그렇지 않으면 도구가 무시된 재정의로 보고합니다.

OpenAI 전용 옵션은 openai 객체 아래에 있습니다.

{  "quality": "low",  "outputFormat": "jpeg",  "openai": {    "background": "opaque",    "moderation": "low",    "outputCompression": 60,    "user": "end-user-42"  }}

openai.background에는 transparent, opaque 또는 auto를 사용할 수 있습니다. 투명 출력에는 outputFormat이 png 또는 webp여야 하며, 투명도를 지원하는 OpenAI 이미지 모델이 필요합니다. OpenClaw는 기본 gpt-image-2 투명 배경 요청을 gpt-image-1.5로 라우팅합니다. openai.outputCompression은 JPEG/WebP 출력에 적용되고 PNG 출력에서는 무시됩니다.

최상위 background 힌트는 제공자 중립적이며, 현재 OpenAI 제공자가 선택된 경우 동일한 OpenAI background 요청 필드에 매핑됩니다. 배경 지원을 선언하지 않은 제공자는 지원되지 않는 매개변수를 수신하는 대신 이를 ignoredOverrides에 반환합니다.

OpenAI 이미지 생성을 api.openai.com 대신 Azure OpenAI 배포를 통해 라우팅하려면 Azure OpenAI 엔드포인트를 참조하세요.

Microsoft Foundry 이미지 생성은 microsoft-foundry/ 제공자 접두사 아래의 배포된 MAI 이미지 배포 이름을 사용합니다. MAI API가 model 필드에 사용자의 배포 이름을 요구하므로 제공자 수준의 기본 모델은 없습니다.

{  agents: {    defaults: {      imageGenerationModel: {        primary: "microsoft-foundry/<deployment-name>",        timeoutMs: 600_000,      },    },  },}

이 제공자는 OpenAI Images API가 아니라 Microsoft Foundry의 MAI API를 사용합니다.

• 생성 엔드포인트: /mai/v1/images/generations
• 편집 엔드포인트: /mai/v1/images/edits
• 인증: AZURE_OPENAI_API_KEY / 제공자 API 키 또는 az login을 통한 Entra ID
• 출력: PNG 이미지 1개
• 크기: 기본값 1024x1024; 너비와 높이는 각각 768px 이상이어야 하며, 총 픽셀 수는 1,048,576 이하여야 함
• 편집: PNG 또는 JPEG 참조 이미지 1개, MAI-Image-2.5-Flash 및 MAI-Image-2.5 배포에서만 지원

프롬프트만 사용하는 생성은 Foundry 엔드포인트만 구성한 상태에서 사용자 지정 배포 이름을 사용할 수 있습니다. 사용자 지정 배포 이름으로 편집하려면 해당 배포가 MAI-Image-2.5-Flash 또는 MAI-Image-2.5를 기반으로 하는지 OpenClaw가 확인할 수 있도록 온보딩/모델 메타데이터가 필요합니다.

현재 MAI 이미지 모델은 MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e 및 MAI-Image-2입니다. 설정 및 채팅 모델 동작은 Microsoft Foundry Plugin을 참조하세요.

OpenRouter 이미지 생성은 동일한 OPENROUTER_API_KEY를 사용하며 OpenRouter의 채팅 완성 이미지 API를 통해 라우팅됩니다. openrouter/ 접두사를 사용하여 OpenRouter 이미지 모델을 선택합니다.

{  agents: {    defaults: {      imageGenerationModel: {        primary: "openrouter/google/gemini-3.1-flash-image-preview",      },    },  },}

OpenClaw는 prompt, count, 참조 이미지 및 Gemini 호환 aspectRatio / resolution 힌트를 OpenRouter로 전달합니다. 현재 내장된 OpenRouter 이미지 모델 단축 이름에는 google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview 및 openai/gpt-5.4-image-2가 포함됩니다. 구성된 Plugin이 노출하는 항목을 확인하려면 action: "list"를 사용합니다.

fal의 Krea 2 모델은 Flux에서 사용하는 일반 image_size 스키마 대신 fal의 네이티브 Krea 스키마를 사용합니다. OpenClaw는 다음을 전송합니다.

• 종횡비 힌트용 aspect_ratio
• 기본값이 medium인 creativity
• image 또는 images가 제공된 경우 image_style_references

더 빠르고 표현력 있는 일러스트레이션에는 Krea 2 Medium을 선택하고, 더 느리지만 세밀하고 사실적이며 질감이 풍부한 표현에는 Krea 2 Large를 선택합니다.

{  agents: {    defaults: {      imageGenerationModel: {        primary: "fal/krea/v2/medium/text-to-image",      },    },  },}

현재 Krea 2는 요청당 이미지 1개를 반환합니다. Krea에는 aspectRatio를 사용하는 것이 좋습니다. OpenClaw는 size를 가장 가까운 지원 Krea 종횡비로 매핑하며, resolution은 누락시키지 않고 거부합니다. Krea 네이티브 창의성 수준을 사용하려면 fal.creativity를 사용합니다.

{  "model": "fal/krea/v2/medium/text-to-image",  "prompt": "A cyber zine portrait with risograph texture",  "aspectRatio": "9:16",  "fal": {    "creativity": "high"  }}

MiniMax 이미지 생성은 번들로 제공되는 두 MiniMax 인증 경로를 통해 사용할 수 있습니다.

• API 키 설정용 minimax/image-01
• OAuth 설정용 minimax-portal/image-01

번들로 제공되는 xAI 제공자는 프롬프트만 있는 요청에 /v1/images/generations를 사용하고, image 또는 images가 있으면 /v1/images/edits를 사용합니다.

• 모델: xai/grok-imagine-image, xai/grok-imagine-image-quality
• 개수: 최대 4개
• 참조: image 1개 또는 images 최대 3개
• 종횡비: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20
• 해상도: 1K, 2K
• 출력: OpenClaw가 관리하는 이미지 첨부 파일로 반환

OpenClaw는 공유 교차 제공자 image_generate 계약에 해당 제어 기능이 존재할 때까지 xAI 네이티브 quality, mask, user 또는 auto 종횡비를 의도적으로 노출하지 않습니다.