Photo Editor API

Edit images using natural language instructions via API.

Overview

The AI Photo Editor API uses natural language understanding technology to make image editing simple and intuitive. Just describe the desired editing effect in words, and AI will intelligently complete the editing based on reference images. Supports color changes, element additions, background replacement, composition adjustments, and more. Upload 1-5 reference images per request.

Endpoint

POST https://api.aluo.ai/api/photo-editor/generate

Request Parameters

Supports two request formats: application/json (recommended) or multipart/form-data

Method 1: JSON Format (Recommended)

Parameter	Type	Required	Description
`prompt`	string	Yes	Editing instruction text
`imageUrls`	array	Yes	Reference image URLs (1-5 images)
`aspectRatio`	string	No	Output aspect ratio (optional)
`outputFormat`	string	No	png \| jpeg \| webp (default: png)
`numImages`	number	No	Number of outputs (default: 1)

Method 2: FormData Format

Parameter	Type	Description
`prompt`	string	Editing instruction text
`file0, file1, ...`	File	Reference image files (max 5)
`aspectRatio`	string	Output aspect ratio (optional)
`outputFormat`	string	png \| jpeg \| webp

Supported Aspect Ratios: 1:1, 3:2, 2:3, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4, 21:9

Response Format

Success Response

Note: After this API returns a taskId, image editing is complete. You can use the taskId to query the status endpoint for result URLs.

{
  "code": 0,
  "success": true,
  "data": {
    "provider": "ai-provider",
    "model": "default",
    "taskId": "edit_123456789",
    "prompt": "Change product color to blue",
    "aspectRatio": "1:1",
    "inputImages": ["https://example.com/ref1.jpg"],
    "numImages": 1
  }
}

Query Result Endpoint

GET https://api.aluo.ai/api/photo-editor/status?taskId=edit_123456789

{
  "code": 0,
  "success": true,
  "data": {
    "status": "SUCCESS",
    "images": [
      { "url": "https://cdn.aluo.ai/edited1.png" }
    ]
  }
}

Example Requests

cURL (JSON Format)

# 步骤 1: 创建编辑任务
curl -X POST https://api.aluo.ai/api/photo-editor/generate \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Change the product color to blue",
    "imageUrls": ["https://example.com/product.jpg"],
    "aspectRatio": "1:1",
    "outputFormat": "png",
    "numImages": 1
  }'

# 步骤 2: 查询任务结果
curl -X GET "https://api.aluo.ai/api/photo-editor/status?taskId=edit_123456789" \
  -H "Authorization: Bearer sk-your-api-key-here"

cURL (FormData Format)

curl -X POST https://api.aluo.ai/api/photo-editor/generate \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -F "prompt=Change the product color to blue" \
  -F "file0=@/path/to/product.jpg" \
  -F "aspectRatio=1:1" \
  -F "outputFormat=png"

Node.js

const fetch = require('node-fetch');

// 步骤 1: 创建编辑任务（JSON 格式）
const createResponse = await fetch(
  'https://api.aluo.ai/api/photo-editor/generate',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk-your-api-key-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'Change the product color to blue',
      imageUrls: ['https://example.com/product.jpg'],
      aspectRatio: '1:1',
      outputFormat: 'png',
      numImages: 1
    })
  }
);

const createResult = await createResponse.json();
const taskId = createResult.data.taskId;

// 步骤 2: 查询任务结果
const statusResponse = await fetch(
  `https://api.aluo.ai/api/photo-editor/status?taskId=${taskId}`,
  {
    headers: {
      'Authorization': 'Bearer sk-your-api-key-here'
    }
  }
);

const statusResult = await statusResponse.json();

if (statusResult.data.status === 'SUCCESS') {
  console.log('Edited images:', statusResult.data.images);
} else if (statusResult.data.status === 'FAILED') {
  console.error('Editing failed');
}

Python

import requests

headers = {
    'Authorization': 'Bearer sk-your-api-key-here',
    'Content-Type': 'application/json'
}

# 步骤 1: 创建编辑任务
create_response = requests.post(
    'https://api.aluo.ai/api/photo-editor/generate',
    headers=headers,
    json={
        'prompt': 'Change the product color to blue',
        'imageUrls': ['https://example.com/product.jpg'],
        'aspectRatio': '1:1',
        'outputFormat': 'png',
        'numImages': 1
    }
)

task_id = create_response.json()['data']['taskId']

# 步骤 2: 查询任务结果
status_response = requests.get(
    f'https://api.aluo.ai/api/photo-editor/status?taskId={task_id}',
    headers={'Authorization': 'Bearer sk-your-api-key-here'}
)

result = status_response.json()

if result['data']['status'] == 'SUCCESS':
    print('Edited images:', result['data']['images'])
elif result['data']['status'] == 'FAILED':
    print('Editing failed')

Editing Examples

Change Color: "Change product to blue"
Add Elements: "Add a coffee cup on the desk"
Replace Background: "Change background to beach scene"
Adjust Composition: "Center the product"
Remove Elements: "Remove watermark from photo"

Credits & Processing Time

Item	Free User	PRO User
Credits Cost	40 credits/edit	35 credits/edit
Processing Time	Usually 10-30 seconds

Credits Deduction: Credits are deducted by the client after obtaining the edited results. If editing fails (status: FAILED), no credits will be deducted.

Tips & Best Practices

More specific descriptions lead to more precise results
Describing one main editing requirement at a time works better
Uploading multiple reference images provides more context
Use clear and concise language, avoid vague expressions
Refer to editing examples when writing descriptions

Common Errors

Error Message	Cause	Solution
`Prompt is required`	No editing instruction	Must provide prompt parameter
`At least one image URL is required`	No reference images	Must provide imageUrls or file0
`Maximum 5 images allowed`	Too many images	Upload at most 5 reference images
`Insufficient credits`	Not enough credits	Recharge credits or upgrade to PRO