全局公共参数

说明：全局公共参数是针对项目而言的，所有请求的 HTTP 类型的接口都需要携带此参数。

认证方式:无需认证

Header请求参数

参数名	参数值	是否必填	参数类型	描述说明
		是	string	-

Query请求参数

参数名	参数值	是否必填	参数类型	描述说明
		是	string	-

Body请求参数

参数名	参数值	是否必填	参数类型	描述说明
		是	string	-

code

说明：状态码是针对项目而言的，所有接口状态码都可参考此文档

暂无数据

概述

已完成

更新时间: 2026-03-30 17:49:58

欢迎使用 AI 图像生成 API。我们提供了图片上传、发起作图任务、查询作图结果、获取作图高清图片、获取任务列表等核心 API 功能。

为了帮助开发者快速、稳定地将 AI 作图能力集成到您的业务中，请在正式调用前仔细阅读本概述。

使用说明

1. 使用前准备

点击右下角 API能力 - 获取API Key

2. 基础地址 (Base URL)

所有 API 请求的基础路径如下：
```
https://ixspy.com
```

3.鉴权认证

本 API 采用标准的 Bearer Token 鉴权机制。开发者在发起任何请求时，都必须在 HTTP 请求头（Headers）中携带分配给您的 API_KEY。

请求头示例：
```
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

4. 核心交互流程

由于 AI 图像生成涉及复杂的 GPU 算力运算，耗时较长（通常在 10秒到 1分钟不等），因此本系统采用异步任务模型。
核心调用流转如下：
1. 前置处理（强烈推荐）：客户端先调用【图片上传】接口（/ai-tool/api/v1/images/upload），将本地图片或 Base64 编码转换为平台 CDN 图片 URL。
2. 发起任务：客户端调用作图接口（如 /ai-tool/api/v1/images/generations/{type}），服务器会立即返回一个全局唯一的 task_id，此时图片并未生成。
3. 轮询状态：客户端拿到 task_id 后，开启一个定时器，循环调用【查询作图结果】接口，实时获取任务当前的执行进度。
4. 获取图片：当状态变为 completed 后，客户端再凭借该 task_id 调用【获取作图高清图片】接口，最终拿到 CDN 上的图片 URL。
交互时序图如下：
最佳实践建议：
- 关于图片传输与多图防错：
  虽然接口支持直接传递 Base64 字符串，但 Base64 编码会使体积膨胀。特别是在使用多图模式（如 custom_composition_multi，最多支持 5 张）或原图体积较大时，直接传 Base64 极易触发网关层的 413 Request Entity Too Large 报错。因此，强烈建议开发者将“先上传拿 URL，再用 URL 数组作图”作为标准开发范式。
- 关于轮询频率：
  建议客户端（或业务后端）在【查询状态】环节，将轮询（Polling）的间隔时间设置在 3~5秒 之间。过于频繁的请求可能会触发限流，间隔过长则会导致用户体验卡顿。

5. 统一响应规范

为了降低业务端的对接成本，本 API 所有的接口均遵循统一的 JSON 响应格式，外层包统一包含 error 状态对象和 data 业务数据载体。

标准成功响应：

{
    "error": {
        "code": 0,
        "message": "success",
        "time": 1773652954
    },
    "data": { ... }
}

标准失败响应

{
    "error": {
        "code": 2004,
        "message": "获取图片失败，请稍后重试",
        "time": 1773388376
    },
    "data": []
}

6. 接口限制

速率限制：每分钟60次请求

图片上传

已完成

更新时间: 2026-03-31 09:49:18

图片上传

接口描述

本接口用于将图片上传至服务器 CDN。为了优化传输效率和存储空间，系统会对图片进行处理：

自动压缩：默认将图片长边限制在 1200px 左右，质量设为 75%。
格式转换：压缩成功的图片将统一转换为 .jpg 格式。
降级保底：若压缩处理失败，系统将自动保存并上传您提交的原始图片。

请求地址

POST /ai-tool/api/v1/images/upload

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`
`Content-Type`	是	String	文件上传用 `multipart/form-data`；Base64 上传用 `application/json`

请求参数 (Body)

您可以根据开发环境选择以下任意一种模式进行上传：

模式 A：文件上传 (File Binary)

参数名	必填	类型	描述
`image`	是	File	原始图片文件（支持 png, jpg, jpeg, webp）。

模式 B：Base64 字符串

参数名	必填	类型	描述
`image_base64`	是	String	图片 Base64 编码（支持带或不带 `data:image/...` 前缀）。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	`0` 表示成功，其他请参考错误码附录。
`error.message`	String	状态描述信息。
`data`	Object	返回的核心数据包。
`data.url`	String	上传成功后的最终 CDN 访问地址。

响应示例

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1773721263
    },
    "data": {
        "url": "https://cdn.ixspy.com/upload/20260313/101/101_69b3c325d5363_852.jpg"
    }
}

{
    "error": {
        "code": 400,
        "message": "无效的上传文件",
        "time": 1773721263
    },
    "data": []
}

代码示例

cURL

文件模式

curl -X POST "https://ixspy.com/ai-tool/api/v1/images/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/path/to/your/photo.jpg"

Base64 模式

curl -X POST "https://ixspy.com/ai-tool/api/v1/images/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }'

PHP (cURL)

文件模式

<?php
$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/images/upload",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => [
        'image' => new CURLFile('/path/to/your/photo.jpg')
    ],
    CURLOPT_HTTPHEADER => ["Authorization: Bearer YOUR_API_KEY"],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Base64 模式

<?php
$curl = curl_init();
$payload = json_encode(['image_base64' => 'data:image/png;base64,iVBOR...']);
curl_setopt_array($curl, [
    CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/images/upload",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer YOUR_API_KEY",
      "Content-Type: application/json"
    ],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Node.js (Axios)

文件模式

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('image', fs.createReadStream('./photo.jpg'));

axios.post('https://ixspy.com/ai-tool/api/v1/images/upload', form, {
    headers: {
        ...form.getHeaders(),
        'Authorization': 'Bearer YOUR_API_KEY'
    }
}).then(res => console.log(res.data));

Base64 模式

const axios = require('axios');

axios.post('https://ixspy.com/ai-tool/api/v1/images/upload', {
    image_base64: "data:image/png;base64,iVBOR..."
}, {
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
}).then(res => console.log(res.data));

Python (Requests)

文件模式

import requests
url = "https://ixspy.com/ai-tool/api/v1/images/upload"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"image": open("photo.jpg", "rb")}
response = requests.post(url, headers=headers, files=files)
print(response.json())

Base64 模式

import requests
url = "https://ixspy.com/ai-tool/api/v1/images/upload"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"image_base64": "data:image/jpeg;base64,/9j/4AAQ..."}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

发起作图任务

已完成

更新时间: 2026-09-15 17:01:14

发起作图任务

接口描述

提交 AI 绘图任务。由于 AI 作图耗时较长（通常在 10-60 秒不等），本接口采用异步模式。调用成功后将返回一个 task_id，开发者需凭此 ID 调用「查询作图结果」接口获取最终图片。

本接口支持多种作图模式，通过 URL 中的 {type} 路径参数进行区分，不同模式下需在请求体中传递特定的参数。

💡 最佳实践提示（防请求体积过大报错）：

虽然接口同时支持 Base64 和 URL 格式的图片传入，但在使用多图模式（如 custom_composition_multi）或单张图片体积较大时，直接传递 Base64 极易导致字符串过长，从而触发 Nginx 等网关层的请求体积超限报错（如 413 Request Entity Too Large）。

强烈建议： 先调用 「图片上传」 接口将本地图片/Base64上传至 CDN 并获取 URL，随后再使用 URL 列表发起作图任务。

请求地址

POST /ai-tool/api/v1/images/generations/{type}

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`
`Content-Type`	是	String	`application/json`

路径参数 (Path Variables)

参数名	必填	类型	描述
`type`	是	String	作图类型。可选值： `custom_composition_multi` (自由构图-多图) `scene_replacement` (场景替换) `product_replacement` (商品替换) `product_recoloring` (商品换色) `partial_redraw` (局部重绘) `smart_expand` (智能延展) `translation` (图片翻译) `ai_upscale_2k` (AI超清-2K)

请求参数 (Body)

1. 公共参数 (Common Parameters)

无论哪种作图类型，都必须或可以选择携带以下参数：

参数名	必填	类型	默认值	描述
`original_image`	是	String / Array	-	原图，支持 Base64 格式（如 `data:image/png;base64,...`）或 URL 格式（公开可访问的图片地址）。 ● 多图模式 (`custom_composition_multi`): 支持 Array，最多支持 5 张图。 ● 其他模式: 支持 String 或 Array ，仅支持 1 张图。强烈建议此处传入通过「图片上传」接口获取的 URL，以避免请求体过大导致报错。
`model`	否	String	`auto`	模型，可选值： `auto` (优先分配资源充足模型) `gemini` (Nano Banana 2/PRO(Gemini3.1 PRO)) `chatgpt` (GPT Image 2.5 Flare(ChatGPT)) `seedream-50-pro` (Seedream-5.0-Pro[无限制版]) 注: 作图类型 - AI超清-2K 不支持 `chatgpt` 模型

2. 差异化参数 (按 `{type}` 区分)

根据 URL 中传入的 {type}，请求体需额外附加以下对应参数：

自由构图-多图 (`custom_composition_multi`)

参数名	必填	类型	描述
`original_image`	是	String / Array	包含多张原图时需使用数组格式，最多支持 5 张，支持 Base64 或 URL 格式。为避免请求体过大导致网关拦截，建议优先使用 URL 格式。
`prompt`	是	String	画面描述，描述人物及环境互动。例如：“背后有bus正好开过，午后的阳光从后面洒在人物身旁...”
`ratios`	是	String	图片比例。例如：“auto”或具体比例。详情参阅枚举变量附录。

场景替换 (`scene_replacement`)

参数名	必填	类型	描述
`prompt`	条件必填	String	场景描述。与 `reference_image` 至少传其一，也可两者同时传入。
`reference_image`	条件必填	String	场景参考图（支持 Base64 或 URL 格式）。与 `prompt` 至少传其一，也可两者同时传入。
`ratios`	是	String	图片比例。例如：“auto”。详情参阅枚举变量附录。

商品替换 (`product_replacement`)

参数名	必填	类型	描述
`reference_image`	是	String	参考图，以此为背景（支持 Base64 或 URL 格式）。
`prompt`	否	String	商品描述。

商品换色 (`product_recoloring`)

参数名	必填	类型	描述
`color`	是	String	目标颜色，需使用十六进制颜色格式，包含透明度（如 `#ff4500ff`）。
`prompt`	否	String	描述具体商品。例如：“模特手中的包”。

局部重绘 (`partial_redraw`)

参数名	必填	类型	描述
`prompt`	是	String	描述如何重绘。例如：“将图片中的花换成桃花”。
`reference_image`	否	String	参考图（支持 Base64 或 URL 格式）。

智能延展 (`smart_expand`)

参数名	必填	类型	描述
`direction`	是	String	延展方向。例如：“top_left”。详情参阅枚举变量附录。
`ratios`	是	String	目标比例。例如：“1:1”。详情参阅枚举变量附录。

图片翻译 (`translation`)

参数名	必填	类型	描述
`source_language`	是	String	需要翻译的原语言。例如：“auto”。详情参阅枚举变量附录。
`target_language`	是	String	目标语言。例如：“Chinese”。详情参阅枚举变量附录。

AI超清-2K (`ai_upscale_2k`)

(仅需公共参数 original_image，无额外差异化参数)

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功，其他请参考错误码附录。
`error.message`	String	状态描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	返回的核心数据包。
`data.task_id`	String	全局唯一的作图任务 ID。
`data.status`	String	当前任务状态，此时通常为 `queued`。

响应示例

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1773384480
    },
    "data": {
        "task_id": 219,
        "status": "queued"
    }
}

{
    "error": {
        "code": 1001,
        "message": "作图类型有误，请检查！",
        "time": 1773384771
    },
    "data": []
}

代码示例

以下代码演示了如何发起一个【自由构图-多图 (custom_composition_multi)】任务。示例中采用了推荐的图片 URL 数组形式进行调用。

cURL

curl -X POST "https://ixspy.com/ai-tool/api/v1/images/generations/custom_composition_multi" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_image": [
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg"
    ],
    "model": "gemini",
    "prompt": "街拍风格，在欧洲繁华的街道上。背后有bus正好开过，午后的阳光从后面洒在人物身旁，人物自然的走在街道上，正面展示着装",
    "ratios": "auto"
  }'

PHP (cURL)

<?php

$curl = curl_init();

$payload = json_encode([
"original_image" => [
    "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
    "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
    "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg"
  ],
"model": "gemini",
"prompt" => "街拍风格，在欧洲繁华的街道上。背后有bus正好开过，午后的阳光从后面洒在人物身旁，人物自然的走在街道上，正面展示着装",
"ratios" => "auto"
]);

curl_setopt_array($curl, [
CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/images/generations/custom_composition_multi",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
  "Authorization: Bearer YOUR_API_KEY",
  "Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}

Node.js (Axios)

const axios = require('axios');

let data = JSON.stringify({
  "original_image": [
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg"
    ],
  "model": "gemini",
  "prompt": "街拍风格，在欧洲繁华的街道上。背后有bus正好开过，午后的阳光从后面洒在人物身旁，人物自然的走在街道上，正面展示着装",
  "ratios": "auto"
});

let config = {
  method: 'post',
  url: 'https://ixspy.com/ai-tool/api/v1/images/generations/custom_composition_multi',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests
import json

url = "https://ixspy.com/ai-tool/api/v1/images/generations/custom_composition_multi"

payload = json.dumps({
  "original_image": [
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg",
      "https://d.ixspy.cn/ai/img/upload/20260326/1333/1333_69c4874a5d9cd_759.jpg"
    ],
  "model": "gemini",
  "prompt": "街拍风格，在欧洲繁华的街道上。背后有bus正好开过，午后的阳光从后面洒在人物身旁，人物自然的走在街道上，正面展示着装",
  "ratios": "auto"
})

headers = {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())

查询作图结果

已完成

更新时间: 2026-04-22 12:56:20

查询作图结果

接口描述

根据发起作图任务时返回的 task_id，轮询或主动查询该任务的当前执行状态及最终图片生成结果。建议轮询间隔设定为 3~5秒。

请求地址

GET /ai-tool/api/v1/images/generations/tasks/{task_id}

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`

路径参数 (Path Variables)

参数名	必填	类型	描述
`task_id`	是	Integer	发起作图任务时返回的任务 ID。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功请求到状态，其他请参考错误码附录。
`error.message`	String	状态描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	任务详情。
`data.status`	String	任务状态枚举：`queued`(排队中), `processing`(进行中), `completed`(完成), `error`(失败)。
`data.sd_image_url`	String	生成的图片 URL。仅在 `status` 为 `completed` 时返回有效数据(标清结果图Url)。

响应示例

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1773652959
    },
    "data": {
        "status": "completed",
        "sd_image_url": "https://cdn.ix-y.com/ai/img/result/20260313/1333/216__sub_69b380ce250c8.png"
    }
}

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1773720225
    },
    "data": {
        "status": "queued"
    }
}

{
    "error": {
        "code": 2002,
        "message": "任务不存在",
        "time": 1773720271
    },
    "data": []
}

代码示例

cURL

curl -X GET "https://ixspy.com/ai-tool/api/v1/images/generations/tasks/219" \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP (cURL)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/images/generations/tasks/219",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js (Axios)

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://ixspy.com/ai-tool/api/v1/images/generations/tasks/219',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests

url = "https://ixspy.com/ai-tool/api/v1/images/generations/tasks/219"

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

获取作图高清图片

已完成

更新时间: 2026-03-17 17:30:32

获取作图高清图片

接口描述

当通过「查询作图结果」接口确认作图任务已完成后，可通过此接口，凭借对应的 task_id 获取最终生成的高清图片地址。

请求地址

GET /ai-tool/api/v1/images/upscale/{task_id}

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`

路径参数 (Path Variables)

参数名	必填	类型	描述
`task_id`	是	Integer	已经完成的作图任务 ID。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功获取，其他请参考错误码附录。
`error.message`	String	状态描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	返回的核心数据包。
`data.hd_image_url`	String	成功时返回高清图片的 URL。

响应示例

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1773721263
    },
    "data": {
        "hd_image_url": "https://cdn.ix-y.com/ai/img/result/20260313/1333/216_69b3c325d5363.jpg"
    }
}

{
    "error": {
        "code": 2004,
        "message": "获取图片失败，请稍后重试",
        "time": 1773388376
    },
    "data": []
}

代码示例

cURL

curl -X GET "https://ixspy.com/ai-tool/api/v1/images/upscale/219 \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP(cURL)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/images/upscale/219",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js(Axios)

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://ixspy.com/ai-tool/api/v1/images/upscale/219',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests

url = "https://ixspy.com/ai-tool/api/v1/images/upscale/219"

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

获取作图任务列表

已完成

更新时间: 2026-04-24 14:56:47

获取作图任务列表

接口描述

获取当前账户下历史作图任务的列表，支持分页和按状态、类型过滤，便于开发者在后台或用户中心进行数据同步和展示。

请求地址

GET /ai-tool/api/v1/images/tasks-list

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`

Query 参数 (Query Parameters)

参数名	必填	类型	默认值	描述
`page`	否	Integer	`1`	当前页码。
`page_size`	否	Integer	`20`	每页数量。
`status`	否	String	`all`	任务状态过滤。可选值：`all`, `queued`(排队中), `processing`(处理中),`completed`(完成), `error`(失败)。
`type`	否	String	`all`	任务类型过滤。例如 `scene_replacement`, `custom_composition` 等。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功请求，其他表示失败。
`error.message`	String	状态或错误描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	成功时返回分页数据包；失败时通常为空或不存在。
`data.total`	Integer	满足条件的总任务条数。
`data.list`	Array	任务列表数组。
`data.list[].task_id`	Integer	任务 ID。
`data.list[].model`	String	模型（如 `gemini`）。
`data.list[].type`	String	任务类型标识（如 `scene_replacement`）。
`data.list[].type_name`	String	任务类型中文名称（如 `场景替换`）。
`data.list[].status`	String	任务状态枚举（`queued`, `completed`, `error`）。
`data.list[].status_name`	String	任务状态中文名称（`排队中`, `完成`, `失败`）。
`data.list[].sd_image_url`	String	成功生成的标清/默认图片地址（未完成时为空）。
`data.list[].hd_image_url`	String	成功生成的高清图片地址（未完成或未生成时为空）。
`data.list[].created_at`	Integer	任务创建时间戳。
`data.list[].integral`	Integer	任务消耗的积分。

响应示例

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1773726537
    },
    "data": {
        "total": 33,
        "list": [
            {
                "task_id": 223,
                "model" : "gemini",
                "type": "product_recoloring",
                "type_name": "商品换色",
                "status": "completed",
                "status_name": "完成",
                "sd_image_url": "https://cdn.ix-y.com/ai/img/result/20260313/1333/216__sub_69b380ce250c8.png",
                "hd_image_url": "https://cdn.ix-y.com/ai/img/result/20260313/1333/216_69b3c325d5363.jpg",
                "created_at": 1773371516,
                "integral": 30
            },
            {
                "task_id": 222,
                "model" : "gemini",
                "type": "product_recoloring",
                "type_name": "商品换色",
                "status": "completed",
                "status_name": "完成",
                "sd_image_url": "https://cdn.ix-y.com/ai/img/result/20260313/1333/216__sub_69b380ce250c8.png",
                "hd_image_url": "",
                "created_at": 1773371516,
                "integral": 30
            },
            {
                "task_id": 221,
                "model" : "gemini",
                "type": "scene_replacement",
                "type_name": "场景替换",
                "status": "queued",
                "status_name": "排队中",
                "sd_image_url": "",
                "hd_image_url": "",
                "created_at": 1773656907,
                "integral": 30
            },
            {
                "task_id": 219,
                "model" : "gemini",
                "type": "custom_composition",
                "type_name": "自由构图",
                "status": "error",
                "status_name": "失败",
                "sd_image_url": "",
                "hd_image_url": "",
                "created_at": 1773384480,
                "integral": 0
            }
        ]
    }
}

代码示例

cURL

curl -X GET "https://ixspy.com/ai-tool/api/v1/images/tasks-list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP(cURL)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/images/tasks-list?page=1&page_size=20",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js (Axios)

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://ixspy.com/api/v1/images/tasks-list?page=1&page_size=20',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests

url = "https://ixspy.com/ai-tool/api/v1/images/tasks-list?page=1&page_size=20"

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

发起视频任务 [内测]

已完成

更新时间: 2026-09-15 16:07:27

发起视频任务

接口描述

提交 AI 视频生成任务。由于视频渲染涉及大量 GPU 算力，耗时通常比图片更长。本接口采用异步模式，调用成功后返回 task_id，开发者需凭此 ID 调用「查询视频结果」接口获取最终视频状态及结果。

💡 参数使用说明：

本接口支持通过 reference_image、first_frame、last_frame 三类图片参数辅助生成视频。

使用时请注意以下限制：

reference_image、first_frame、last_frame 三者合计传入的图片数量不能超过 3 张。

如果传入 last_frame，则必须同时传入 first_frame。

图片支持 Base64 或 URL 格式，建议优先使用通过「图片上传」接口获取的 URL，以避免请求体过大导致网关拦截。

请求地址

POST /ai-tool/api/v1/video/generations

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`
`Content-Type`	是	String	`application/json`

请求参数 (Body)

参数名	必填	类型	默认值	描述
`reference_image`	否	Array		参考图数组，最多支持 `3` 张，支持 Base64 或 URL 格式。
`first_frame`	否	String		首帧图，支持 Base64 或 URL 格式，仅支持 `1` 张。
`last_frame`	否	String		尾帧图，支持 Base64 或 URL 格式，仅支持 `1` 张。如传入该字段，则必须同时传入 `first_frame`。
`prompt`	是	String		视频画面描述。需详细描述图片中角色、物品的互动、风格、材质及场景背景。
`model`	否	String	`gemini`	模型，可选值： `gemini` (Veo 3.1 (Gemini3.1 PRO)) `seedance-20-fast` (Seedance 2.0 fast[无限制版]) `seedance-25` (Seedance 2.5[无限制版]) `seedance-20` (Seedance 2.0[无限制版]) `seedance-20-mini` (Seedance 2.0 mini[无限制版])
`ratios`	否	String	`16:9`	视频比例，可选值：模型为gemini时：`16:9`、`9:16` 模型为seedance-20-fast时：`16:9`、`9:16`、`4:3`、`3:4` 模型为seedance-25时：`16:9`、`9:16`、`4:3`、`3:4`、`21:9` 模型为seedance-20时：`16:9`、`9:16`、`4:3`、`3:4`、`21:9` 模型为seedance-20-mini时：`16:9`、`9:16`、`4:3`、`3:4`
`resolution`	否	String	`720p`	清晰度，可选值：模型为gemini时：`720p` 模型为seedance-20-fast时：`720p`、`480p` 模型为seedance-25时：`720p`、`480p`、`1080p` 模型为seedance-20时：`720p`、`480p`、`1080p`、`4k` 模型为seedance-20-mini时：`720p`、`480p`
`time`	否	Integer	`10`	时间（秒），可选值：模型为gemini时：`10` 模型为seedance-20-fast时：`10`、`8`、`15` 模型为seedance-25时：`10`、`8`、`15`、`20`、`25`、`30` 模型为seedance-20时：`10`、`8`、`15` 模型为seedance-20-mini时：`10`、`8`、`15`

请求参数约束与兼容规则

reference_image、first_frame、last_frame 三类图片合计传入数量不能超过 3 张。
last_frame 不能单独传入，传入时必须同时提供 first_frame。
prompt 为必填参数。
参数自适应与降级规则：
- 当传入的 ratios 不在该 model 支持的列表中时，系统不会阻断报错，而是自动重置为默认值 16:9。
- 当传入的 resolution 不在该 model 支持的列表中时，系统不会阻断报错，而是自动重置为默认值 720p。
- 当传入的 time 不在该 model 支持的列表中时，系统不会阻断报错，而是自动重置为默认值 10。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功。
`error.message`	String	状态描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	返回的核心数据包。
`data.task_id`	Integer	全局唯一的视频任务 ID。
`data.status`	String	当前任务状态，通常为 `queued`。

响应示例

成功响应

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1775110186
    },
    "data": {
        "task_id": 389,
        "status": "queued"
    }
}

失败响应

{
    "error": {
        "code": 1000,
        "message": "请输入描述！",
        "time": 1775119315
    },
    "data": []
}

代码示例

cURL

curl -X POST "https://ixspy.com/ai-tool/api/v1/video/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini",
    "prompt": "image1为波克比的图片，image2为伊布的图片。以写实风格和场景，制作这两张图片中角色的1/7比例商业化手办，并放置在同一张图中。将手办放置在客厅木制桌面上，底座为圆形透明亚克力材质，无任何文字。图片中背景为家庭住宅客厅背景。",
    "reference_image": [
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg",
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png"
    ],
    "ratios": "16:9",
    "resolution": "720p",
    "time": 10
  }'

PHP (cURL)

<?php

$curl = curl_init();

$payload = json_encode([
  "model" => "gemini",
  "prompt" => "image1为波克比的图片，image2为伊布的图片。以写实风格和场景，制作这两张图片中角色的1/7比例商业化手办，并放置在同一张图中。将手办放置在客厅木制桌面上，底座为圆形透明亚克力材质，无任何文字。图片中背景为家庭住宅客厅背景。",
  "reference_image" => [
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg",
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png"
  ],
  "ratios" => "16:9",
  "resolution" => "720p",
  "time" => 10
]);

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/video/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js (Axios)

const axios = require('axios');

const data = {
  model: 'gemini',
  prompt: 'image1为波克比的图片，image2为伊布的图片。以写实风格和场景，制作这两张图片中角色的1/7比例商业化手办，并放置在同一张图中。将手办放置在客厅木制桌面上，底座为圆形透明亚克力材质，无任何文字。图片中背景为家庭住宅客厅背景。',
  reference_image: [
    'https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg',
    'https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png'
  ],
  ratios: '16:9',
  resolution: '720p',
  time: 10
};

axios.post('https://ixspy.com/ai-tool/api/v1/video/generations', data, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
})
.then((response) => {
  console.log(response.data);
})
.catch((error) => {
  console.error(error);
});

Python (Requests)

import requests

url = "https://ixspy.com/ai-tool/api/v1/video/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "model": "gemini",
    "prompt": "image1为波克比的图片，image2为伊布的图片。以写实风格和场景，制作这两张图片中角色的1/7比例商业化手办，并放置在同一张图中。将手办放置在客厅木制桌面上，底座为圆形透明亚克力材质，无任何文字。图片中背景为家庭住宅客厅背景。",
    "reference_image": [
        "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg",
        "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png"
    ],
    "ratios": "16:9",
    "resolution": "720p",
    "time": 10
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

查询视频结果 [内测]

已完成

更新时间: 2026-04-22 12:56:40

查询视频结果

接口描述

根据发起视频任务时返回的 task_id，轮询或主动查询该任务的当前执行状态及最终视频生成结果。由于视频生成较慢，建议轮询间隔设定为 15~20秒。

请求地址

GET /ai-tool/api/v1/video/generations/tasks/{task_id}

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`

路径参数 (Path Variables)

参数名	必填	类型	描述
`task_id`	是	Integer	发起视频任务时返回的任务 ID。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功请求到状态，其他请参考错误码附录。
`error.message`	String	状态描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	任务详情。
`data.status`	String	任务状态枚举：`queued`(排队中), `processing`(进行中), `completed`(完成), `error`(失败)。
`data.video_url`	String	生成的视频 URL。仅在 `status` 为 `completed` 时返回有效数据。

响应示例

成功完成响应

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1775120482
    },
    "data": {
        "status": "completed",
        "video_url": "https://d.ixspy.cn/ai/img/task_results/2026-04-01/task_e5c76df01775110304.969636.mp4"
    }
}

任务排队中或处理中响应

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1775120400
    },
    "data": {
        "status": "processing"
    }
}

任务不存在或失败响应

{
    "error": {
        "code": 2002,
        "message": "任务不存在",
        "time": 1775120558
    },
    "data": []
}

代码示例

cURL

curl -X GET "https://ixspy.com/ai-tool/api/v1/video/generations/tasks/389" \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP (cURL)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/video/generations/tasks/389",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js (Axios)

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://ixspy.com/ai-tool/api/v1/video/generations/tasks/389',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data, null, 2));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests

url = "https://ixspy.com/ai-tool/api/v1/video/generations/tasks/389"

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers)

print(response.json())

获取视频任务列表 [内测]

已完成

更新时间: 2026-04-02 17:54:21

获取视频任务列表

接口描述

获取当前账户下历史视频作图任务的列表，支持分页和按状态过滤，便于开发者在后台或用户中心进行数据同步和展示。

请求地址

GET /ai-tool/api/v1/video/tasks-list

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`

Query 参数 (Query Parameters)

参数名	必填	类型	默认值	描述
`page`	否	Integer	`1`	当前页码。
`page_size`	否	Integer	`20`	每页数量。
`status`	否	String	`all`	任务状态过滤。可选值：`all`, `queued`(排队中), `processing`(处理中), `completed`(完成), `error`(失败)。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功请求，其他表示失败。
`error.message`	String	状态或错误描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	成功时返回分页数据包；失败时通常为空或不存在。
`data.total`	Integer	满足条件的总任务条数。
`data.list`	Array	任务列表数组。
`data.list[].task_id`	Integer	任务 ID。
`data.list[].type_name`	String	任务类型名称（如 `视频制作`）。
`data.list[].status`	String	任务状态枚举（`queued`, `processing`, `completed`, `error`）。
`data.list[].status_name`	String	任务状态中文名称（如 `排队中`, `完成`, `失败`）。
`data.list[].video_url`	String	成功生成的视频地址（未完成时为空）。
`data.list[].created_at`	Integer	任务创建时间戳。
`data.list[].integral`	Integer	任务消耗的积分。

响应示例

成功响应

json
{
"error": {
"code": 0,
"message": "",
"time": 1775121943
},
"data": {
"total": 2,
"list": [
{
"task_id": 389,
"type_name": "视频制作",
"status": "completed",
"status_name": "完成",
"video_url": "https://d.ixspy.cn/ai/img/task_results/2026-04-01/task_e5c76df01775110304.969636.mp4",
"created_at": 1775110184,
"integral": 100
},
{
"task_id": 388,
"type_name": "视频制作",
"status": "queued",
"status_name": "排队中",
"video_url": "",
"created_at": 1775110076,
"integral": 100
}
]
}
}

代码示例

cURL

curl -X GET "https://ixspy.com/ai-tool/api/v1/video/tasks-list?page=1&page_size=20&status=all" \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP (cURL)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/video/tasks-list?page=1&page_size=20&status=all",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js (Axios)

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://ixspy.com/ai-tool/api/v1/video/tasks-list?page=1&page_size=20&status=all',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data, null, 2));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests

url = "https://ixspy.com/ai-tool/api/v1/video/tasks-list"
querystring = {"page": "1", "page_size": "20", "status": "all"}

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.json())

发起对话任务 [内测]

已完成

更新时间: 2026-05-08 19:05:23

发起对话任务

接口描述

提交 AI 对话任务。支持传入图片和文字提示进行多模态对话。

💡 最佳实践提示：

虽然接口同时支持 Base64 和 URL 格式的图片传入，但在多图或原图体积较大时，直接传递 Base64 极易导致请求体过大触发网关拦截。强烈建议： 先调用 「图片上传」 接口将本地图片/Base64 上传至 CDN 并获取 URL，随后再使用 URL 格式发起对话任务。

请求地址

POST /ai-tool/api/v1/chat/generations

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`
`Content-Type`	是	String	`application/json`

请求参数 (Body)

参数名	必填	类型	默认值	描述
`original_image`	否	Array	-	原图数组，最多支持 5 张图。支持 Base64 格式（如 `data:image/png;base64,...`）或 URL 格式（公开可访问的图片地址）。为避免请求体过大，建议优先使用通过「图片上传」接口获取的 URL。
`prompt`	是	String	-	对话提示内容。描述你希望 AI 针对图片或文本进行回答的问题或指令。
`model`	否	String	`auto`	模型。可选值： `auto`（优先分配资源充足模型） `gemini`（Gemini） `chatgpt`（ChatGPT）。
`model_tier`	否	String	`Flash`	模型规格。可选值：`Flash`（快速）、`Pro`。仅在 `model=gemini` 时生效。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功。
`error.message`	String	状态描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	返回的核心数据包。
`data.status`	String	当前任务状态，`completed`(完成), `error`(失败)。
`data.html`	String	AI 对话生成的富文本内容（HTML 格式）。仅在 `status` 为 `completed` 时返回有效数据。

响应示例

成功响应

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1776323334
    },
    "data": {
        "status": "completed",
        "html": "<div _ngcontent-ng-c3498727022=\"\" inline-copy-host=\"\" class=\"markdown markdown-main-panel stronger enable-updated-hr-color\" id=\"model-response-message-contentr_d7356f2c7724ea41\" aria-live=\"polite\" aria-busy=\"false\" dir=\"ltr\" style=\"--animation-duration: 400ms; --fade-animation-function: linear;\"><p data-path-to-node=\"0\">这两张图片都是宝可梦（Pokémon）系列中经典角色的Q版可爱风（Chibi）插画：</p><ul data-path-to-node=\"1\"><li><p data-path-to-node=\"1,0,0\"><b data-path-to-node=\"1,0,0\" data-index-in-node=\"0\">第一张图片：</b> 画的是宝可梦<b data-path-to-node=\"1,0,0\" data-index-in-node=\"13\">波克比（Togepi）</b>。它有着淡黄色的身体和星型的脑袋，下半身包裹在带有红色和蓝色三角形花纹的蛋壳里。波克比闭着一只眼睛，脸颊上有明显的红晕，小手举在胸前，表情看起来非常调皮可爱。背景为纯白色。</p></li><li><p data-path-to-node=\"1,1,0\"><b data-path-to-node=\"1,1,0\" data-index-in-node=\"0\">第二张图片：</b> 画的是宝可梦<b data-path-to-node=\"1,1,0\" data-index-in-node=\"13\">伊布（Eevee）</b>。这只伊布正蜷缩成一团安静地休息或睡觉。它的眼睛眯成了两条弯弯的缝，嘴巴呈现可爱的\"ω\"形状。伊布有着标志性的大耳朵、棕色的身体以及脖子周围一圈毛茸茸的奶油色颈毛。背景是与伊布毛色相呼应的纯棕色，底部带有非常细小的版权声明文字。</p></li></ul></div>"
    }
}

失败响应

{
    "error": {
        "code": 1000,
        "message": "请输入对话内容！",
        "time": 1776322487
    },
    "data": []
}

代码示例

cURL

curl -X POST "https://ixspy.com/ai-tool/api/v1/chat/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_image": [
        "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg",
        "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png"
    ],
    "prompt": "描述一下这2张图片的内容",
    "model": "auto",
    "model_tier": "Flash"
  }'

PHP (cURL)

<?php

$curl = curl_init();

$payload = json_encode([
  "original_image" => [
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg",
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png"
  ],
  "prompt" => "描述一下这2张图片的内容",
  "model" => "auto",
  "model_tier" => "Flash"
]);

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/chat/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js (Axios)

const axios = require('axios');

let data = JSON.stringify({
  "original_image": [
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg",
      "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png"
  ],
  "prompt": "描述一下这2张图片的内容",
  "model": "auto",
  "model_tier": "Flash"
});

let config = {
  method: 'post',
  url: 'https://ixspy.com/ai-tool/api/v1/chat/generations',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests
import json

url = "https://ixspy.com/ai-tool/api/v1/chat/generations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "original_image": [
        "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-1.jpg",
        "https://cdn.ixspy.cn/aliexpress/aiTool/demo/custom-multiple/2-2.png"
    ],
    "prompt": "描述一下这2张图片的内容",
    "model": "auto",
    "model_tier": "Flash"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

获取对话任务列表 [内测]

已完成

更新时间: 2026-04-16 16:08:52

获取对话任务列表

接口描述

获取当前账户下历史对话任务的列表，支持分页和按状态过滤，便于开发者在后台或用户中心进行数据同步和展示。

请求地址

GET /ai-tool/api/v1/chat/tasks-list

请求头 (Headers)

参数名	必填	类型	描述
`Authorization`	是	String	鉴权 Token，格式：`Bearer {API_KEY}`

Query 参数 (Query Parameters)

参数名	必填	类型	默认值	描述
`page`	否	Integer	`1`	当前页码。
`page_size`	否	Integer	`20`	每页数量。
`status`	否	String	`all`	任务状态过滤。可选值：`all`, `queued`(排队中), `processing`(进行中), `completed`(完成), `error`(失败)。

响应参数

参数名	类型	描述
`error`	Object	状态与错误信息包。
`error.code`	Integer	业务状态码，`0` 表示成功请求，其他表示失败。
`error.message`	String	状态或错误描述信息。
`error.time`	Integer	服务器响应时间戳。
`data`	Object	成功时返回分页数据包；失败时通常为空或不存在。
`data.total`	Integer	满足条件的总任务条数。
`data.list`	Array	任务列表数组。
`data.list[].task_id`	Integer	任务 ID。
`data.list[].type_name`	String	任务类型名称（如 `对话任务`）。
`data.list[].status`	String	任务状态枚举（`queued`, `processing`, `completed`, `error`）。
`data.list[].status_name`	String	任务状态中文名称（如 `排队中`, `进行中`, `完成`, `失败`）。
`data.list[].result`	String	AI 对话生成的富文本内容（HTML 格式）。未完成时为空字符串。
`data.list[].created_at`	Integer	任务创建时间戳。
`data.list[].integral`	Integer	任务消耗的积分。

响应示例

成功响应

{
    "error": {
        "code": 0,
        "message": "",
        "time": 1776325719
    },
    "data": {
        "total": 3,
        "list": [
            {
                "task_id": 486,
                "type_name": "对话任务",
                "status": "queued",
                "status_name": "排队中",
                "result": "",
                "created_at": 1776322486,
                "integral": 10
            },
            {
                "task_id": 471,
                "type_name": "对话任务",
                "status": "completed",
                "status_name": "完成",
                "result": "<div ...>AI 对话生成的 HTML 富文本内容</div>",
                "created_at": 1776075066,
                "integral": 10
            },
            {
                "task_id": 428,
                "type_name": "对话任务",
                "status": "error",
                "status_name": "失败",
                "result": "",
                "created_at": 1776068998,
                "integral": 0
            }
        ]
    }
}

代码示例

cURL

curl -X GET "https://ixspy.com/ai-tool/api/v1/chat/tasks-list?page=1&page_size=20&status=all" \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP (cURL)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://ixspy.com/ai-tool/api/v1/chat/tasks-list?page=1&page_size=20&status=all",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Node.js (Axios)

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://ixspy.com/ai-tool/api/v1/chat/tasks-list?page=1&page_size=20&status=all',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data, null, 2));
})
.catch((error) => {
  console.log(error);
});

Python (Requests)

import requests

url = "https://ixspy.com/ai-tool/api/v1/chat/tasks-list"
querystring = {"page": "1", "page_size": "20", "status": "all"}

headers = {
  'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.json())

附录

更新时间: 2026-03-16 16:22:15

目录参数

认证方式:继承父级

错误码附录

已完成

更新时间: 2026-03-25 18:34:46

Code	描述
0	成功
400	系统错误，请联系客服
401	权限验证失败
402	系统繁忙，请稍后重试
429	超出请求限制
1000	缺少必要的参数
1001	作图类型有误，请检查！
1002	积分不足，请求充值后再试
1003	请上传原始图片
1004	上传图片格式错误
1005	上传图片失败
1006	原图数量超出限制
2001	请传入任务id
2002	任务不存在
2003	任务未完成，请稍后再试
2004	获取图片失败，请稍后重试

枚举变量附录

已完成

更新时间: 2026-09-15 17:04:13

变量	名称	值	含义
type	作图类型	custom_composition_multi	自由构图-多图
		scene_replacement	场景替换
		product_replacement	商品替换
		product_recoloring	商品换色
		partial_redraw	局部重绘
		smart_expand	智能延展
		translation	图片翻译
		ai_upscale_2k	AI超清-2K
model	模型	gemini	Nano Banana 2/PRO(Gemini3.1 PRO)
		chatgpt	GPT Image 2.5 Flare(ChatGPT)
		seedream-50-pro	Seedream-5.0-Pro[无限制版]
ratios	比例	1:1
		16:9
		9:16
		4:3
		3:4
		21:9
		3:2
		2:3
		5:4
		4:5
		auto	自适应
direction	延展方向	top_left	左上
		top	上
		top_right	右上
		left	左
		auto	自适应
		right	右
		bottom_left	左下
		bottom	下
		bottom_right	右下
source_language	需要翻译的语言	auto	自动
		Chinese	中文
		English	英文
		Russian	俄语
		Spanish	西班牙语
		French	法语
		German	德语
		Italian	意大利语
		Dutch	荷兰语
		Portuguese	葡萄牙语
		Vietnamese	越南语
		Turkish	土耳其语
		Malay	马来语
		Thai	泰语
		Polish	波兰语
		Indonesian	印尼语
		Korean	韩文
		Japanese	日语
		Arabic	阿拉伯语
target_language	目标语言	Chinese	中文
		English	英文
		Russian	俄语
		Spanish	西班牙语
		French	法语
		German	德语
		Italian	意大利语
		Dutch	荷兰语
		Portuguese	葡萄牙语
		Vietnamese	越南语
		Turkish	土耳其语
		Malay	马来语
		Thai	泰语
		Polish	波兰语
		Indonesian	印尼语
		Korean	韩文
		Japanese	日语
		Arabic	阿拉伯语

脚本示例

更新时间: 2026-03-19 17:08:51

目录参数

认证方式:继承父级

Python脚本示例

已完成

更新时间: 2026-04-03 18:43:06

SDK： https://github.com/ixspyinc/ixspy-ai-api-python

脚本示例

import os
import sys
from ixspy_ai_api import ImageClient

# 分步骤调用, 任务方法和参数都已约定好

API_KEY = 'YOUR_KEY'
FOLDER_PATH = os.path.dirname(os.path.abspath(sys.argv[0])) + os.sep
original_image_path = FOLDER_PATH + 'images/speaker.jpg'

client = ImageClient(api_key=API_KEY)

task_id = client.create_custom_composition(
    original_image=original_image_path,
    prompt="移除产品背景，只保留白色背景产品图",
)
print(f"任务ID: {task_id}")

# 轮询等待完成
result = client.wait_for_completion(task_id, poll_interval=3, timeout=180)

# 可和预生成的图片 examples/images/demo_result_create_custom_composition.png 对比
print("标清图URL:", result['sd_image_url'])

# 高清圖需要額外時間,這裏選擇多等待半分鐘
print('等待半分钟后获取高清图')
time.sleep(30)

# 获取高清图
hd_url = client.get_hd_image(task_id)
print("高清图URL:", hd_url)

Node.js脚本示例

已完成

更新时间: 2026-03-19 18:39:45

demo: https://cdn.ixspy.cn/aliexpress/aiTool/api/ixspy-img-api-nodejs.zip

脚本示例

const path = require('path');
const { AIImageGenerator } = require('../src/index');

/**
 * 分步骤调用示例
 */
async function main() {
    // 替换为您的真实 KEY
    const API_KEY = 'YOUR_KEY';

    // 解析图片绝对路径
    const originalImagePath = path.join(__dirname, 'images', 'speaker.jpg');

    // 实例化 SDK 客户端
    const client = new AIImageGenerator(API_KEY);

    try {
        console.log("🚀 开始发起自由构图任务...");
        const taskId = await client.createCustomComposition(
            originalImagePath,
            "移除产品背景，只保留白色背景产品图"
        );
        console.log(`✅ 任务创建成功，任务ID: ${taskId}`);

        // 轮询等待任务完成 (每隔3秒查询一次，最多等待180秒)
        console.log("⏳ 等待任务生成中...");
        const result = await client.waitForCompletion(taskId, 3, 180);

        console.log("\n🎉 生成完成!");
        console.log("👉 标清图URL:", result.sd_image_url);

        // 可选：获取高清大图 (注意，该操作可能会额外扣费，详情参考官网API计费文档)
        console.log("\n🖼️ 正在获取高清图...");
        const hdUrl = await client.getHdImage(taskId);
        console.log("👉 高清图URL:", hdUrl);

    } catch (error) {
        console.error("❌ 任务执行失败:");
        console.error(error.message);
    }
}

main();

使用说明

1. 使用前准备

2. 基础地址 (Base URL)

3.鉴权认证

请求头示例：

4. 核心交互流程

5. 统一响应规范

6. 接口限制

图片上传

接口描述

请求地址

请求头 (Headers)

请求参数 (Body)

模式 A：文件上传 (File Binary)

模式 B：Base64 字符串

响应参数

响应示例

代码示例

cURL

文件模式

Base64 模式

PHP (cURL)

文件模式

Base64 模式

Node.js (Axios)

文件模式

Base64 模式

Python (Requests)

文件模式

Base64 模式

发起作图任务

接口描述

请求地址

请求头 (Headers)

路径参数 (Path Variables)

请求参数 (Body)

1. 公共参数 (Common Parameters)

2. 差异化参数 (按 {type} 区分)

自由构图-多图 (custom_composition_multi)

场景替换 (scene_replacement)

商品替换 (product_replacement)

商品换色 (product_recoloring)

局部重绘 (partial_redraw)

智能延展 (smart_expand)

图片翻译 (translation)

AI超清-2K (ai_upscale_2k)

响应参数

响应示例

代码示例

以下代码演示了如何发起一个【自由构图-多图 (custom_composition_multi)】任务。示例中采用了推荐的图片 URL 数组形式进行调用。

cURL

PHP (cURL)

Node.js (Axios)

Python (Requests)

查询作图结果

接口描述

请求地址

请求头 (Headers)

路径参数 (Path Variables)

响应参数

响应示例

代码示例

cURL

PHP (cURL)

Node.js (Axios)

Python (Requests)

获取作图高清图片

接口描述

请求地址

请求头 (Headers)

路径参数 (Path Variables)

响应参数

响应示例

代码示例

cURL

PHP(cURL)

Node.js(Axios)

Python (Requests)

获取作图任务列表

接口描述

2. 差异化参数 (按 `{type}` 区分)

自由构图-多图 (`custom_composition_multi`)

场景替换 (`scene_replacement`)

商品替换 (`product_replacement`)

商品换色 (`product_recoloring`)

局部重绘 (`partial_redraw`)

智能延展 (`smart_expand`)

图片翻译 (`translation`)

AI超清-2K (`ai_upscale_2k`)