Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oxen.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ParameterTypeRequiredDefaultDescription
modelstringyes—Image editing model (e.g. qwen-image-edit, nano-banana-2-edit, xai-grok-imagine-image-edit)
promptstringyes—Description of the edit to apply.
input_imagestring/arrayyes—URL(s) of the image to edit. Some models accept an array; see per-model reference.
response_formatstringno"url""url" returns a hosted URL. "b64_json" returns base64-encoded image bytes inline.
target_namespacestringnocurrent userNamespace to save results and bill to. Can be an organization name.

​
Examples

​
Basic edit

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"])

​
Multi-image input

Some models accept an array of URLs in input_image. Consult the per-model reference for how each model uses them: 
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",
        ],
    },
)
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

ConditionError
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.