Tạo hình ảnh

Một ghi đè model theo từng lệnh gọi chỉ thử nhà cung cấp/mô hình đó và không tiếp tục sang primary/fallback đã cấu hình hoặc các nhà cung cấp được tự động phát hiện.

Một mặc định của nhà cung cấp chỉ được đưa vào danh sách ứng viên khi OpenClaw thực sự có thể xác thực nhà cung cấp đó. Đặt agents.defaults.mediaGenerationAutoProviderFallback: false để chỉ dùng các mục model, primary và fallbacks rõ ràng.

Đặt agents.defaults.imageGenerationModel.timeoutMs cho các backend tạo ảnh chậm. Tham số công cụ timeoutMs theo từng lệnh gọi ghi đè mặc định đã cấu hình, và các mặc định đã cấu hình ghi đè các mặc định của nhà cung cấp do Plugin tạo. Các nhà cung cấp ảnh được lưu trữ trên Google và OpenRouter dùng mặc định 180 giây; tạo ảnh Microsoft Foundry MAI, xAI và Azure OpenAI dùng 600 giây. Các lệnh gọi công cụ động của Codex dùng mặc định bridge image_generate 120 giây và tôn trọng cùng ngân sách thời gian chờ khi được cấu hình, bị giới hạn bởi mức tối đa bridge công cụ động 600000 ms của OpenClaw.

Dùng action: "list" để kiểm tra các nhà cung cấp hiện đang được đăng ký, mô hình mặc định của chúng và các gợi ý biến môi trường xác thực.

Tạo ảnh OpenAI mặc định dùng openai/gpt-image-2. Nếu một hồ sơ OAuth openai được cấu hình, OpenClaw tái sử dụng cùng hồ sơ OAuth mà các mô hình chat thuê bao Codex dùng và gửi yêu cầu ảnh qua backend Codex Responses. Các URL cơ sở Codex cũ như https://chatgpt.com/backend-api được chuẩn hóa thành https://chatgpt.com/backend-api/codex cho yêu cầu ảnh. OpenClaw không âm thầm chuyển dự phòng sang OPENAI_API_KEY cho yêu cầu đó - để buộc định tuyến trực tiếp qua OpenAI Images API, hãy cấu hình rõ ràng models.providers.openai với API key, URL cơ sở tùy chỉnh hoặc endpoint Azure.

Các mô hình openai/gpt-image-1.5, openai/gpt-image-1 và openai/gpt-image-1-mini vẫn có thể được chọn rõ ràng. Dùng gpt-image-1.5 cho đầu ra PNG/WebP nền trong suốt; API gpt-image-2 hiện tại từ chối background: "transparent".

gpt-image-2 hỗ trợ cả tạo ảnh từ văn bản và chỉnh sửa ảnh tham chiếu qua cùng công cụ image_generate. OpenClaw chuyển tiếp prompt, count, size, quality, outputFormat và ảnh tham chiếu tới OpenAI. OpenAI không nhận trực tiếp aspectRatio hoặc resolution; khi có thể, OpenClaw ánh xạ chúng vào một size được hỗ trợ, nếu không công cụ sẽ báo chúng là các ghi đè bị bỏ qua.

Các tùy chọn riêng của OpenAI nằm dưới đối tượng openai:

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

openai.background chấp nhận transparent, opaque hoặc auto; đầu ra trong suốt yêu cầu outputFormat là png hoặc webp và một mô hình ảnh OpenAI có khả năng trong suốt. OpenClaw định tuyến các yêu cầu nền trong suốt mặc định gpt-image-2 sang gpt-image-1.5. openai.outputCompression áp dụng cho đầu ra JPEG/WebP và bị bỏ qua cho đầu ra PNG.

Gợi ý background cấp cao nhất là trung lập với nhà cung cấp và hiện ánh xạ tới cùng trường yêu cầu background của OpenAI khi nhà cung cấp OpenAI được chọn. Các nhà cung cấp không khai báo hỗ trợ nền sẽ trả nó trong ignoredOverrides thay vì nhận tham số không được hỗ trợ.

Để định tuyến tạo ảnh OpenAI qua một deployment Azure OpenAI thay vì api.openai.com, xem endpoint Azure OpenAI.

Tạo ảnh Microsoft Foundry dùng tên deployment ảnh MAI đã triển khai dưới tiền tố nhà cung cấp microsoft-foundry/. Không có mô hình mặc định cấp nhà cung cấp vì MAI API yêu cầu tên deployment của bạn trong trường model:

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

Nhà cung cấp dùng MAI API của Microsoft Foundry, không phải OpenAI Images API:

• Endpoint tạo: /mai/v1/images/generations
• Endpoint chỉnh sửa: /mai/v1/images/edits
• Xác thực: AZURE_OPENAI_API_KEY / API key của nhà cung cấp, hoặc Entra ID qua az login
• Đầu ra: một ảnh PNG
• Kích thước: mặc định 1024x1024; chiều rộng và chiều cao mỗi chiều phải ít nhất 768 px, và tổng số pixel tối đa là 1.048.576
• Chỉnh sửa: một ảnh tham chiếu PNG hoặc JPEG, chỉ được hỗ trợ bởi các deployment MAI-Image-2.5-Flash và MAI-Image-2.5

Tạo chỉ từ prompt có thể dùng tên deployment tùy chỉnh chỉ với endpoint Foundry được cấu hình. Chỉnh sửa bằng tên deployment tùy chỉnh cần metadata onboarding/mô hình để OpenClaw có thể xác minh rằng deployment được hỗ trợ bởi MAI-Image-2.5-Flash hoặc MAI-Image-2.5.

Các mô hình ảnh MAI hiện tại là MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e và MAI-Image-2. Xem Plugin Microsoft Foundry để biết thiết lập và hành vi mô hình chat.

Tạo ảnh OpenRouter dùng cùng OPENROUTER_API_KEY và định tuyến qua image API chat completions của OpenRouter. Chọn các mô hình ảnh OpenRouter bằng tiền tố openrouter/:

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

OpenClaw chuyển tiếp prompt, count, ảnh tham chiếu và các gợi ý aspectRatio / resolution tương thích Gemini tới OpenRouter. Các lối tắt mô hình ảnh OpenRouter tích hợp hiện tại gồm google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview và openai/gpt-5.4-image-2. Dùng action: "list" để xem Plugin đã cấu hình của bạn cung cấp những gì.

Các mô hình Krea 2 trên fal dùng schema Krea gốc của fal thay vì schema image_size chung mà Flux dùng. OpenClaw gửi:

• aspect_ratio cho các gợi ý tỷ lệ khung hình
• creativity, mặc định là medium
• image_style_references khi image hoặc images được cung cấp

Chọn Krea 2 Medium để có minh họa biểu cảm nhanh hơn và Krea 2 Large để có giao diện chân thực và nhiều chi tiết/kết cấu hơn nhưng chậm hơn:

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

Krea 2 hiện trả về một ảnh cho mỗi yêu cầu. Ưu tiên aspectRatio cho Krea; OpenClaw ánh xạ size sang tỷ lệ khung hình Krea được hỗ trợ gần nhất và từ chối resolution cho Krea thay vì bỏ qua nó. Dùng fal.creativity khi bạn muốn mức độ sáng tạo Krea gốc:

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

Tạo ảnh MiniMax khả dụng qua cả hai đường dẫn xác thực MiniMax được đóng gói:

• minimax/image-01 cho các thiết lập API key
• minimax-portal/image-01 cho các thiết lập OAuth

Nhà cung cấp xAI được đóng gói dùng /v1/images/generations cho các yêu cầu chỉ có prompt và /v1/images/edits khi có image hoặc images.

• Mô hình: xai/grok-imagine-image, xai/grok-imagine-image-quality
• Số lượng: tối đa 4
• Tham chiếu: một image hoặc tối đa năm images
• Tỷ lệ khung hình: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
• Độ phân giải: 1K, 2K
• Đầu ra: được trả về dưới dạng tệp đính kèm ảnh do OpenClaw quản lý

OpenClaw cố ý không phơi bày quality, mask, user hoặc các tỷ lệ khung hình chỉ gốc bổ sung của xAI cho đến khi các điều khiển đó tồn tại trong hợp đồng image_generate dùng chung xuyên nhà cung cấp.