图片编辑 API

通过 API 使用自然语言指令编辑图像。

概述

AI 图片编辑 API 通过自然语言理解技术，让图片编辑变得简单直观。只需用文字描述您想要的编辑效果，AI 就能基于参考图片智能完成编辑。支持颜色更改、元素添加、背景替换、构图调整等多种编辑需求。每次可上传 1-5 张参考图片。

接口地址

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

请求参数

支持两种请求格式：application/json（推荐）或 multipart/form-data

方式一：JSON 格式（推荐）

参数	类型	必填	说明
`prompt`	string	是	编辑指令文本
`imageUrls`	array	是	参考图片 URL 数组（1-5 张）
`aspectRatio`	string	否	输出宽高比（可选）
`outputFormat`	string	否	png \| jpeg \| webp （默认 png）
`numImages`	number	否	生成数量（默认 1）

方式二：FormData 格式

参数	类型	说明
`prompt`	string	编辑指令文本
`file0, file1, ...`	File	参考图片文件（最多 5 个）
`aspectRatio`	string	输出宽高比（可选）
`outputFormat`	string	png \| jpeg \| webp

支持的宽高比: 1:1, 3:2, 2:3, 16:9, 9:16, 4:3, 3:4, 4:5, 5:4, 21:9

响应格式

成功响应

注意：此 API 返回 taskId 后,图片编辑已完成。您可以使用 taskId 查询状态接口获取结果 URL。

{
  "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
  }
}

查询结果接口

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

请求示例

cURL（JSON 格式）

# 步骤 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 格式）

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')

编辑示例

更改颜色："将产品改为蓝色"
添加元素："在桌面上添加一杯咖啡"
更换背景："将背景改为海滩场景"
调整构图："将产品居中放置"
移除元素："移除照片中的水印"

积分消耗与处理时间

项目	免费用户	PRO 用户
积分消耗	40 积分/次	35 积分/次
处理时间	通常 10-30 秒

积分扣除说明: 积分由客户端在获取编辑结果后扣除。如果编辑失败（status: FAILED），不会扣除积分。

使用技巧

描述越具体，生成效果越精准
一次描述一个主要编辑需求效果更好
上传多张参考图可提供更多上下文信息
使用简洁明了的语言，避免模糊表述
可以参考编辑示例来撰写描述

常见错误

错误信息	原因	解决方案
`Prompt is required`	未提供编辑指令	必须提供 prompt 参数
`At least one image URL is required`	未提供参考图片	必须提供 imageUrls 或 file0
`Maximum 5 images allowed`	参考图片过多	最多上传 5 张参考图片
`Insufficient credits`	积分不足	充值积分或升级到 PRO