Image problems
Fixes for Flux image errors: edit_unsupported, invalid_reference_image, price_exceeds_max_price, moderation_blocked, a key that cannot use a model, and sizes that are ignored.
Each entry gives the symptom, the cause and the fix, keyed by the status and code in the error. The full contract is in the images reference; the guide is Make and edit images.
400 edit_unsupported
Symptom. POST /v1/images/edits answers 400 with code: "edit_unsupported".
Cause. The model you named cannot edit with reference images.
Fix. Use flux-image, or leave model out (edits default to it), or use flux-image-pro. Generation works on every model; editing does not.
400 invalid_reference_image
Symptom. An edit answers 400 with code: "invalid_reference_image".
Cause. One of these:
- A file is not PNG, JPEG or WebP.
- A file is over 10 MB, or all files together are over 20 MB.
- You sent more than 4 images, or none.
Fix. Convert or shrink the files, and send between one and 4 under image[].
402 price_exceeds_max_price
Symptom. The call answers 402 with code: "price_exceeds_max_price" and no image.
Cause. The final price, including any pay-as-you-go markup, was above the max_price you set. The image may have been made, but it is not returned and you are not charged.
Fix. Raise max_price, or pick a cheaper model from the table on Make and edit images. quality and n also change the price.
402 premium_locked
Symptom. Every image call answers 402 with code: "premium_locked". From your agent, image_generate answers premium_locked and then disappears from its tool list.
Cause. Images are a paid ability, and this key's plan is not paid and cleared yet. Nothing was made or charged.
Fix. Upgrade in Billing. See Plans. Restart your agent afterwards so it lists the tool again.
400 moderation_blocked
Symptom. A generation or edit answers 400 with code: "moderation_blocked" and type image_generation_user_error.
Cause. The prompt, or a reference image, was refused by the model's content rules.
Fix. Change the prompt. Retrying the same one fails the same way. This is not a fault on our side, so a retry loop will not help.
401 or 403 permission_error
Symptom. A key that works for chat answers 401 or 403 with code: "permission_error" on images.
Cause. The key is wrong or revoked, or its model allowlist does not include the image model you asked for.
Fix. Check the key on your keys page. If it has an allowlist, add the image model, or use a key without one. GET /v1/models with the same key lists the models it can use.
403 organization_must_be_verified
Symptom. One model answers 403 with code: "organization_must_be_verified".
Cause. That model is not available for this request.
Fix. Pick another model. If it keeps happening on the default, contact support.
The image is not the size I asked for
Cause. Most models make their own fixed size and ignore size.
Fix. Resize the result yourself, or try another model. size is not an error when ignored.
404 on every image call
Cause. Images are not switched on for this account.
Fix. Contact support.
502 capability_unavailable
Cause. The image could not be made or priced right now. You are not charged.
Fix. Retry after a short wait. In a stream, the same failure arrives as a frame with "type": "error".