Image Editing

Edit images using text prompts

Endpoint

POST /api/ai/images/edit

Edit an existing image using a text prompt. The request blocks until the edited image is ready.

Request Parameters

Parameter	Type	Required	Default	Description
model	string	yes	—	Image editing model (e.g. qwen-image-edit, nano-banana-2-edit, xai-grok-imagine-image-edit)
prompt	string	yes	—	Description of the edit to apply.
input_image	string/array	yes	—	URL(s) of the image to edit. Some models accept an array; see per-model reference.
response_format	string	no	"url"	"url" returns a hosted URL. "b64_json" returns base64-encoded image bytes inline.
target_namespace	string	no	current user	Namespace to save results and bill to. Can be an organization name.

Examples

Basic edit

Python

import requests

response = requests.post(
    "https://hub.oxen.ai/api/ai/images/edit",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image-edit",
        "prompt": "Make the background blue",
        "input_image": "https://example.com/my-photo.jpg",
    },
)

data = response.json()
print("Image URL:", data["images"][0]["url"])

curl -X POST https://hub.oxen.ai/api/ai/images/edit \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-edit",
    "prompt": "Make the background blue",
    "input_image": "https://example.com/my-photo.jpg"
  }'

Multi-image input

Some models accept an array of URLs in input_image. Consult the per-model reference for how each model uses them:

Python

import requests

response = requests.post(
    "https://hub.oxen.ai/api/ai/images/edit",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-2-edit",
        "prompt": "Combine these references into a single scene",
        "input_image": [
            "https://example.com/reference-a.png",
            "https://example.com/reference-b.png",
        ],
    },
)

curl -X POST https://hub.oxen.ai/api/ai/images/edit \
  -H "Authorization: Bearer $OXEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-edit",
    "prompt": "Combine these references into a single scene",
    "input_image": [
      "https://example.com/reference-a.png",
      "https://example.com/reference-b.png"
    ]
  }'

Whether a model accepts a single image or an array of images is part of its schema. See each model’s API reference for the exact type.

Response

Same format as /ai/images/generate:

{
  "model": "qwen-image-edit",
  "created": 1775090400,
  "images": [
    {
      "url": "https://hub.oxen.ai/api/repos/.../files/.../image.png?..."
    }
  ]
}

Errors

Condition	Error
Image URL not accessible	"... 403 Client Error: Forbidden for url: ..."
Model not found	"Model not found: <name>"

The input_image URL must be publicly downloadable. URLs that require authentication or block automated access will fail. Data URIs (data:image/...;base64,...) work as an alternative but aren’t recommended for production.