悠船 API 接口参考
API 接口参考
本文档详细介绍悠船 API 的全部接口定义,包括图片生成、视频生成、账户管理及 Moodboard 四大模块。
说明
接口总览
图片生成
接口名称 | 方法 | 路径 | 分类 | 说明 |
图像生成 | POST | /v1/tob/diffusion | 直接生成 | 通过文本和/或图片生成图像,支持文生图、图生图、多图提示 |
变化 | POST | /v1/tob/variation | 二次编辑 | 生成与原图相似但有变化的图像 |
高清 | POST | /v1/tob/upscale | 二次编辑 | 提升图像质量和分辨率 |
重新执行任务 | POST | /v1/tob/reroll | 二次编辑 | 使用相同参数重新生成图像 |
延展 | POST | /v1/tob/pan | 二次编辑 | 向指定方向延展图像 |
扩图 | POST | /v1/tob/outpaint | 二次编辑 | 向所有方向同时扩展图像 |
区域重绘 | POST | /v1/tob/inpaint | 二次编辑 | 重新生成图像中的特定区域 |
重塑 | POST | /v1/tob/remix | 二次编辑 | 使用新提示词调整图像 |
编辑 | POST | /v1/tob/edit | 二次编辑 | 在画布上编辑现有图像 |
高级编辑 | POST | /v1/tob/upload-paint | 直接生成 | 上传图像并进行高级编辑 |
转绘 | POST | /v1/tob/retexture | 直接生成 | 改变图像的纹理风格 |
移除背景 | POST | /v1/tob/remove-background | 直接生成 | 自动去除图像背景 |
增强 | POST | /v1/tob/enhance | 二次编辑 | 增强图片质量(仅支持 draft 类型任务) |
视频生成
接口名称 | 方法 | 路径 | 分类 | 说明 |
图生视频 | POST | /v1/tob/video-diffusion | 直接生成 | 基于图像或文本生成短视频 |
视频延长 | POST | /v1/tob/extend-video | 二次编辑 | 扩展现有视频时长(最多 4 次) |
视频高清 | POST | /v1/tob/video-upscale | 二次编辑 | 生成 1080P 高清视频 |
账户管理
接口名称 | 方法 | 路径 | 说明 |
查询任务信息 | GET | /v1/tob/job/{jobId} | 获取特定任务的详情和状态 |
查询消耗历史 | GET | /v1/tob/costs | 获取消费历史(支持分页和时间范围过滤) |
月度消耗详情 | GET | /v1/tob/cost-monthly | 查看月度消耗统计 |
获取账户信息 | GET | /v1/tob/subscribe | 查询订阅状态和剩余资源 |
回调通知演示 | POST | /v1/tob/callback | 测试回调功能 |
Moodboard(灵感收集板)
接口名称 | 方法 | 路径 | 说明 |
创建 Moodboard | POST | /v1/tob/moodboard | 创建灵感收集板 |
更新 Moodboard | PUT | /v1/tob/moodboard/{id} | 修改现有收集板 |
获取 Moodboard 列表 | GET | /v1/tob/moodboards | 查询所有收集板(支持分页) |
图片生成接口
图像生成
图像生成是最核心的接口,同时支持纯文本生图和图片引导生图两种模式。您可以只传入文本描述来生成图像,也可以在提示词中嵌入一张或多张图片 URL 来实现图生图、多图融合等效果。此外,还支持通过参数引入角色参考、风格参考和万物引用等高级图片引导能力。
相关阅读:
请求路径: POST /v1/tob/diffusion
请求参数:
参数 | 类型 | 必填 | 说明 |
text | String | 是 | 提示词。支持纯文本、嵌入图片 URL(实现图生图)、以及通过设置生成参数 |
callback | String | 否 | 异步回调地址,任务完成后系统会将结果推送至该 URL |
使用场景
该接口通过 text 字段中的不同内容组合,覆盖以下常见场景:
场景 | text 字段格式 | 说明 |
纯文本生图 | 描述文本 [--参数] | 仅通过文字描述生成图像 |
单图 + 文本 | [图片URL ]描述文本 [--参数] | 参考一张图片,结合文字描述生成新图像 |
多图融合 | [图片URL1] [图片URL2] [--参数] | 混合多张图片的风格和元素(无文本) |
多图 + 文本 | [图片URL1] [图片URL2] 描述文本 [--参数] | 多张参考图配合文字获得更精确的引导 |
角色参考 | 描述文本 --cref [人物图片URL] | 在新图中保持指定角色的面部、发型、服装一致性 |
风格参考 | 描述文本 --sref [风格图片URL] | 迁移参考图的视觉风格(颜色、纹理、光照)到新创作 |
万物引用 | 描述文本 --oref [物体图片URL] | 将参考图中的角色或物体放入新场景(仅 v7) |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/diffusion"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"text": "A beautiful sunset over the mountains",
"callback": "https://your-callback-url.com"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/diffusion"
data := map[string]string{
"text": "A beautiful sunset over the mountains",
"callback": "https://your-callback-url.com",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Diffusion {
public static void main(String[] args) throws Exception {
String url = "https://ali.youchuan.cn/v1/tob/diffusion";
String json = """
{
"text": "A beautiful sunset over the mountains",
"callback": "https://your-callback-url.com"
}
""";
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/diffusion" \
-H "Content-Type: application/json" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-d '{
"text": "A beautiful sunset over the mountains",
"callback": "https://your-callback-url.com"
}'const url = "https://ali.youchuan.cn/v1/tob/diffusion";
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
},
body: JSON.stringify({
text: beautiful sunset over the mountains",
callback: "https://your-callback-url.com"
})
});
const data = await response.json();
console.log(data);图片引导的关键参数
参数 | 说明 | 取值范围 |
--iw | 图像提示权重,控制参考图对结果的影响程度。详见图像提示词 | v6/v6.1/v7/v8: 0-3,niji 6: 0-2,niji 5:0-2,默认 1 |
--cref | 角色参考图 URL。详见角色参考 | 支持 v6、v6.1、niji 6 |
--cw | 角色参考权重 | 0-100,默认 100 |
--sref | 风格参考图 URL(最多 20 个)。详见风格参考 | 支持所有图像模型 |
--sw | 风格参考权重 | 0-1000,默认 100 |
--sv | 风格算法版本 | 1-4(v7 支持 1-6),默认 4 |
--oref | 万物引用图 URL(仅 1 张)。详见万物引用 | 仅 v7 |
--ow | 万物引用权重 | 1-1000,默认 100 |
说明
响应示例
成功响应(200):
{ "jobId": "d4f7a2b1-8e3c-4f5a-9b6d-1234567890ab", "comment": "JobStatusCreated", "text": "A beautiful sunset over the mountains", "urls": [], "cost": 0}说明 任务提交后 urls 为空数组,图像生成完成后通过回调通知或查询任务接口获取 urls 中的图片地址。cost 在任务成功(JobStatusSuccess)后更新为实际消耗金额。
回调通知(任务完成后推送至 callback 地址):
{ "jobId": "d4f7a2b1-8e3c-4f5a-9b6d-1234567890ab", "comment": "JobStatusSuccess", "text": "A beautiful sunset over the mountains", "urls": [ "https://cdn.youchuan.cn/attachments/xxxxx/image_0.png", "https://cdn.youchuan.cn/attachments/xxxxx/image_1.png", "https://cdn.youchuan.cn/attachments/xxxxx/image_2.png", "https://cdn.youchuan.cn/attachments/xxxxx/image_3.png" ], "cost": 0.6}错误响应示例:
{ "code": 400, "message": "Invalid_Prompt_Parameter", "reason": "提示词参数格式错误:--ar 参数值必须为正整数比值"}变化
生成与原图相似但有一定变化的图像,适用于在已有创作基础上探索不同可能性。
请求路径: POST /v1/tob/variation
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
imageNo | Integer | 是 | 原始图像编号,取值范围 0-3 |
type | Integer | 是 | 变化程度:0 为轻微变化,1 为强烈变化 |
callback | String | 否 | 异步回调地址 |
remixPrompt | String | 否 | 重塑提示词,用于在变化基础上调整方向 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/variation"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345",
"imageNo": 0,
"type": 1
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/variation"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "12345",
"imageNo": 0,
"type": 1,
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\",\"imageNo\":0,\"type\":1}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/variation"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/variation" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345",
"imageNo": 0,
"type": 1
}'fetch('https://ali.youchuan.cn/v1/tob/variation', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345',
imageNo: 0,
type: 1
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));高清
提升图像质量和分辨率,支持多种放大模式。
请求路径: POST /v1/tob/upscale
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
imageNo | Integer | 是 | 原始图像编号 |
type | Integer | 是 | 放大模式:0 标准、1 创意、2 v5_2x、3 v5_4x |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/variation"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345",
"imageNo": 0,
"type": 1
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/variation"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "12345",
"imageNo": 0,
"type": 1,
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\",\"imageNo\":0,\"type\":1}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/variation"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/variation" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345",
"imageNo": 0,
"type": 1
}'fetch('https://ali.youchuan.cn/v1/tob/variation', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345',
imageNo: 0,
type: 1
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "f1a2b3c4-5d6e-7f8a-9b0c-112233445566", "comment": "JobStatusCreated", "urls": [], "cost": 0}任务完成后(高清图像返回单张高分辨率 URL):
{ "jobId": "f1a2b3c4-5d6e-7f8a-9b0c-112233445566", "comment": "JobStatusSuccess", "urls": [ "https://cdn.youchuan.cn/attachments/xxxxx/upscaled_0.png" ], "cost": 0.6}重新执行任务
使用与原始任务相同的参数重新生成图像,适用于对当前生成结果不满意、希望获得不同随机结果的场景。
请求路径: POST /v1/tob/reroll
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
callback | String | 否 | 异步回调地址 |
代码示例
mport requests
url = "https://ali.youchuan.cn/v1/tob/reroll"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {"jobId": "12345"}
response = requests.post(url, headers=headers, json=data)
print(response.json())data := map[string]interface{}{
"jobId": "12345",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", "https://ali.youchuan.cn/v1/tob/reroll", bytes.NewBuffer(jsonData))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))String json = """
{"jobId": "12345"}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/reroll"))
.header("Content-Type", "application/json")
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());curl -X POST "https://ali.youchuan.cn/v1/tob/reroll" \
-H "Content-Type: application/json" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-d '{"jobId": "12345"}'const response = await fetch("https://ali.youchuan.cn/v1/tob/reroll", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
},
body: JSON.stringify({ jobId: "12345" })
});
console.log(await response.json());响应示例
成功响应(200):
{ "jobId": "c3d9e1a4-5f2b-4c8a-a7d0-fedcba987654", "comment": "JobStatusCreated", "urls": [], "cost": 0}延展
向指定方向延展图像内容。
请求路径: POST /v1/tob/pan
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
imageNo | Integer | 是 | 原始图像编号 |
direction | Integer | 是 | 延展方向:0 下、1 右、2 上、3 左 |
scale | Float | 是 | 延展比例,取值范围 1.1-3.0 |
remixPrompt | String | 否 | 延展区域提示词 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/pan"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345",
"imageNo": 0,
"direction": 1,
"scale": 1.5
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/pan"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "12345",
"imageNo": 0,
"direction": 1,
"scale": 1.5,
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\",\"imageNo\":0,\"direction\":1,\"scale\":1.5}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/pan"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/pan" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345",
"imageNo": 0,
"direction": 1,
"scale": 1.5
}'fetch('https://ali.youchuan.cn/v1/tob/pan', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345',
imageNo: 0,
direction: 1,
scale: 1.5
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "comment": "JobStatusCreated", "urls": [], "cost": 0}扩图
向所有方向同时扩展图像内容。
请求路径: POST /v1/tob/outpaint
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
imageNo | Integer | 是 | 原始图像编号 |
scale | Float | 是 | 扩展比例,取值范围 1.1-2.0 |
remixPrompt | String | 否 | 扩图区域提示词 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/outpaint"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345",
"imageNo": 0,
"scale": 1.5
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/outpaint"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "12345",
"imageNo": 0,
"scale": 1.5,
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\",\"imageNo\":0,\"scale\":1.5}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/outpaint"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/outpaint" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345",
"imageNo": 0,
"scale": 1.5
}'fetch('https://ali.youchuan.cn/v1/tob/outpaint', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345',
imageNo: 0,
scale: 1.5
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "comment": "JobStatusCreated", "urls": [], "cost": 0}区域重绘
重新生成图像中的特定区域,可通过蒙版指定需重绘的范围。
请求路径: POST /v1/tob/inpaint
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
imageNo | Integer | 是 | 原始图像编号 |
mask | Object | 是 | 蒙版定义,支持 areas(坐标区域)或 url(蒙版图片地址) |
remixPrompt | String | 否 | 重绘区域的描述提示词 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/inpaint"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345",
"imageNo": 0,
"mask": {
"areas": [{
"width": 100,
"height": 100,
"points": [10,10,10,100,100,100,100,10]
}]
},
"remixPrompt": "Add a tree in the center"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/inpaint"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "12345",
"imageNo": 0,
"mask": map[string]interface{}{
"areas": []map[string]interface{}{
{
"width": 100,
"height": 100,
"points": []int{10,10,10,100,100,100,100,10},
},
},
},
"remixPrompt": "Add a tree in the center",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\",\"imageNo\":0,\"mask\":{\"areas\":[{\"width\":100,\"height\":100,\"points\":[10,10,10,100,100,100,100,10]}]},\"remixPrompt\":\"Add a tree in the center\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/inpaint"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/inpaint" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345",
"imageNo": 0,
"mask": {
"areas": [{
"width": 100,
"height": 100,
"points": [10,10,10,100,100,100,100,10]
}]
},
"remixPrompt": "Add a tree in the center"
}'fetch('https://ali.youchuan.cn/v1/tob/inpaint', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345',
imageNo: 0,
mask: {
areas: [{
width: 100,
height: 100,
points: [10,10,10,100,100,100,100,10]
}]
},
remixPrompt: 'Add a tree in the center'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "comment": "JobStatusCreated", "urls": [], "cost": 0}重塑
使用新的提示词在保留原图结构的基础上调整图像。提示词编写技巧请参见 提示词指南。
请求路径: POST /v1/tob/remix
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
imageNo | Integer | 是 | 原始图像编号 |
remixPrompt | String | 是 | 新的提示词 |
mode | Integer | 否 | 重塑模式:0 强烈(默认)、1 细微 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/edit"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345",
"imageNo": 0,
"canvas": {
"width": 1024,
"height": 1024
},
"imgPos": {
"width": 512,
"height": 512,
"x": 256,
"y": 256
},
"remixPrompt": "A beautiful landscape with mountains"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/edit"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "12345",
"imageNo": 0,
"canvas": map[string]int{
"width": 1024,
"height": 1024,
},
"imgPos": map[string]int{
"width": 512,
"height": 512,
"x": 256,
"y": 256,
},
"remixPrompt": "A beautiful landscape with mountains",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\",\"imageNo\":0,\"canvas\":{\"width\":1024,\"height\":1024},\"imgPos\":{\"width\":512,\"height\":512,\"x\":256,\"y\":256},\"remixPrompt\":\"A beautiful landscape with mountains\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/edit"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/edit" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345",
"imageNo": 0,
"canvas": {
"width": 1024,
"height": 1024
},
"imgPos": {
"width": 512,
"height": 512,
"x": 256,
"y": 256
},
"remixPrompt": "A beautiful landscape with mountains"
}'fetch('https://ali.youchuan.cn/v1/tob/edit', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345',
imageNo: 0,
canvas: {
width: 1024,
height: 1024
},
imgPos: {
width: 512,
height: 512,
x: 256,
y: 256
},
remixPrompt: 'A beautiful landscape with mountains'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "d4e5f6a7-b8c9-0123-def0-234567890123", "comment": "JobStatusCreated", "urls": [], "cost": 0}编辑
在画布上对现有图像进行编辑操作。
请求路径: POST /v1/tob/edit
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID |
imageNo | Integer | 是 | 原始图像编号 |
canvas | Object | 是 | 画布尺寸:width(像素宽)、height(像素高) |
imgPos | Object | 是 | 图像位置:width、height、x(水平位移)、y(垂直位移) |
remixPrompt | String | 是 | 编辑描述提示词 |
mask | Object | 否 | 原图重绘区域 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/upload-paint"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"imgUrl": "https://example.com/images/sample.jpg",
"mask": {
"areas": [{
"width": 100,
"height": 100,
"points": [10,10,10,100,100,100,100,10]
}]
},
"canvas": {
"width": 1024,
"height": 1024
},
"imgPos": {
"width": 512,
"height": 512,
"x": 256,
"y": 256
},
"remixPrompt": "A beautiful mountain scene with trees"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/upload-paint"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"imgUrl": "https://example.com/images/sample.jpg",
"mask": map[string]interface{}{
"areas": []map[string]interface{}{
{
"width": 100,
"height": 100,
"points": []int{10,10,10,100,100,100,100,10},
},
},
},
"canvas": map[string]int{
"width": 1024,
"height": 1024,
},
"imgPos": map[string]int{
"width": 512,
"height": 512,
"x": 256,
"y": 256,
},
"remixPrompt": "A beautiful mountain scene with trees",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"imgUrl\":\"https://example.com/images/sample.jpg\",\"mask\":{\"areas\":[{\"width\":100,\"height\":100,\"points\":[10,10,10,100,100,100,100,10]}]},\"canvas\":{\"width\":1024,\"height\":1024},\"imgPos\":{\"width\":512,\"height\":512,\"x\":256,\"y\":256},\"remixPrompt\":\"A beautiful mountain scene with trees\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/upload-paint"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/upload-paint" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"imgUrl": "https://example.com/images/sample.jpg",
"mask": {
"areas": [{
"width": 100,
"height": 100,
"points": [10,10,10,100,100,100,100,10]
}]
},
"canvas": {
"width": 1024,
"height": 1024
},
"imgPos": {
"width": 512,
"height": 512,
"x": 256,
"y": 256
},
"remixPrompt": "A beautiful mountain scene with trees"
}'fetch('https://ali.youchuan.cn/v1/tob/upload-paint', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
imgUrl: 'https://example.com/images/sample.jpg',
mask: {
areas: [{
width: 100,
height: 100,
points: [10,10,10,100,100,100,100,10]
}]
},
canvas: {
width: 1024,
height: 1024
},
imgPos: {
width: 512,
height: 512,
x: 256,
y: 256
},
remixPrompt: 'A beautiful mountain scene with trees'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "e5f6a7b8-c9d0-1234-ef01-345678901234", "comment": "JobStatusCreated", "urls": [], "cost": 0}高级编辑
上传外部图像并进行高级编辑操作。
请求路径: POST /v1/tob/upload-paint
请求参数:
参数 | 类型 | 必填 | 说明 |
imgUrl | String | 是 | 待编辑图像的 URL 地址 |
mask | Object | 是 | 蒙版定义 |
canvas | Object | 是 | 画布尺寸定义 |
imgPos | Object | 是 | 图像在画布中的位置 |
remixPrompt | String | 是 | 编辑描述提示词 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/upload-paint"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"imgUrl": "https://example.com/images/sample.jpg",
"mask": {
"areas": [{
"width": 100,
"height": 100,
"points": [10,10,10,100,100,100,100,10]
}]
},
"canvas": {
"width": 1024,
"height": 1024
},
"imgPos": {
"width": 512,
"height": 512,
"x": 256,
"y": 256
},
"remixPrompt": "A beautiful mountain scene with trees"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/upload-paint"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"imgUrl": "https://example.com/images/sample.jpg",
"mask": map[string]interface{}{
"areas": []map[string]interface{}{
{
"width": 100,
"height": 100,
"points": []int{10,10,10,100,100,100,100,10},
},
},
},
"canvas": map[string]int{
"width": 1024,
"height": 1024,
},
"imgPos": map[string]int{
"width": 512,
"height": 512,
"x": 256,
"y": 256,
},
"remixPrompt": "A beautiful mountain scene with trees",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"imgUrl\":\"https://example.com/images/sample.jpg\",\"mask\":{\"areas\":[{\"width\":100,\"height\":100,\"points\":[10,10,10,100,100,100,100,10]}]},\"canvas\":{\"width\":1024,\"height\":1024},\"imgPos\":{\"width\":512,\"height\":512,\"x\":256,\"y\":256},\"remixPrompt\":\"A beautiful mountain scene with trees\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/upload-paint"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/upload-paint" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"imgUrl": "https://example.com/images/sample.jpg",
"mask": {
"areas": [{
"width": 100,
"height": 100,
"points": [10,10,10,100,100,100,100,10]
}]
},
"canvas": {
"width": 1024,
"height": 1024
},
"imgPos": {
"width": 512,
"height": 512,
"x": 256,
"y": 256
},
"remixPrompt": "A beautiful mountain scene with trees"
}'fetch('https://ali.youchuan.cn/v1/tob/upload-paint', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
imgUrl: 'https://example.com/images/sample.jpg',
mask: {
areas: [{
width: 100,
height: 100,
points: [10,10,10,100,100,100,100,10]
}]
},
canvas: {
width: 1024,
height: 1024
},
imgPos: {
width: 512,
height: 512,
x: 256,
y: 256
},
remixPrompt: 'A beautiful mountain scene with trees'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "f6a7b8c9-d0e1-2345-f012-456789012345", "comment": "JobStatusCreated", "urls": [], "cost": 0}转绘
改变图像的纹理和风格。可借助 风格参考(--sref) 实现更精确的风格迁移。
请求路径: POST /v1/tob/retexture
请求参数:
参数 | 类型 | 必填 | 说明 |
imgUrl | String | 是 | 待转绘图像的 URL 地址 |
remixPrompt | String | 是 | 描述目标风格的提示词 |
callback | String | 否 | 异步回调地址 |
注意 转绘功能需要使用 v6.1 及以上版本模型。
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/retexture"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"imgUrl": "https://example.com/images/sample.jpg",
"remixPrompt": "Convert to oil painting style"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/retexture"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]string{
"imgUrl": "https://example.com/images/sample.jpg",
"remixPrompt": "Convert to oil painting style",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"imgUrl\":\"https://example.com/images/sample.jpg\",\"remixPrompt\":\"Convert to oil painting style\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/retexture"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/retexture" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"imgUrl": "https://example.com/images/sample.jpg",
"remixPrompt": "Convert to oil painting style"
}'fetch('https://ali.youchuan.cn/v1/tob/retexture', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
imgUrl: 'https://example.com/images/sample.jpg',
remixPrompt: 'Convert to oil painting style'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "a7b8c9d0-e1f2-3456-0123-567890123456", "comment": "JobStatusCreated", "urls": [], "cost": 0}移除背景
自动识别并去除图像背景。
请求路径: POST /v1/tob/remove-background
请求参数:
参数 | 类型 | 必填 | 说明 |
imgUrl | String | 是 | 待处理图像的 URL 地址 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/remove-background"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"imgUrl": "https://example.com/images/sample.jpg"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/remove-background"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]string{
"imgUrl": "https://example.com/images/sample.jpg",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"imgUrl\":\"https://example.com/images/sample.jpg\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/remove-background"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/remove-background" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"imgUrl": "https://example.com/images/sample.jpg"
}'fetch('https://ali.youchuan.cn/v1/tob/remove-background', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
imgUrl: 'https://example.com/images/sample.jpg'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "b8c9d0e1-f2a3-4567-1234-678901234567", "comment": "JobStatusCreated", "urls": [], "cost": 0}任务完成后(返回去除背景的透明 PNG):
{ "jobId": "b8c9d0e1-f2a3-4567-1234-678901234567", "comment": "JobStatusSuccess", "urls": [ "https://cdn.youchuan.cn/attachments/xxxxx/removed_bg.png" ], "cost": 0.6}增强
增强图片质量,仅适用于 draft 类型任务生成的图像。关于草图模式的详细说明请参见 速度模式 → 草图模式。
请求路径: POST /v1/tob/enhance
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始任务 ID(必须为 draft 模式任务) |
imageNo | Integer | 是 | 原始图像编号 |
callback | String | 否 | 异步回调地址 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/enhance"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345",
"imageNo": 0
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/enhance"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]string{
"jobId": "12345",
"imageNo": "0"
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\",\"imageNo\":\"0\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/enhance"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/enhance" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345",
"imageNo": "0"
}'fetch('https://ali.youchuan.cn/v1/tob/enhance', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345',
imageNo: '0'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "c9d0e1f2-a3b4-5678-2345-789012345678", "comment": "JobStatusCreated", "urls": [], "cost": 0}视频生成接口
图生视频
将图像转化为 5 秒短视频。支持以悠船生成的图片或自定义图片作为视频首帧。jobId 与 prompt 二选一。运动强度、尾帧指定、视频循环等高级控制请参见 视频高级控制。
请求路径: POST /v1/tob/video-diffusion
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 条件必填 | 悠船任务 ID(与 prompt 二选一) |
imageNo | Integer | 条件必填 | 图像编号(搭配 jobId 使用) |
prompt | String | 条件必填 | 包含图片链接的提示词(与 jobId 二选一) |
videoType | Integer | 否 | 视频分辨率:0 为 480p(默认),1 为 720p |
callback | String | 否 | 异步回调地址 |
视频规格:
原图比例 | 视频比例 | 分辨率示例 |
1:1 | 1:1 | 624×624 |
4:3 | 77:58 | 720×544 |
2:3 | 2:3 | 512×768 |
16:9 | 91:51 | 832×464 |
说明 720p 视频的费用是 480p 的 3.2 倍。
代码示例
import requests
# 文本生成视频
url = "https://ali.youchuan.cn/v1/tob/video-diffusion"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"prompt": "A beautiful sunset over the ocean with gentle waves",
"callback": "https://your-callback-url.com"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
# 基于图像生成视频
data_with_image = {
"jobId": "existing_job_id",
"imageNo": 0,
"prompt": "Make this image move with gentle animation",
"callback": "https://your-callback-url.com"
}
response = requests.post(url, headers=headers, json=data_with_image)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/video-diffusion"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
// 文本生成视频
data := map[string]interface{}{
"prompt": "A beautiful sunset over the ocean with gentle waves",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"prompt\":\"A beautiful sunset over the ocean with gentle waves\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/video-diffusion"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}# 文本生成视频
curl -X POST "https://ali.youchuan.cn/v1/tob/video-diffusion" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A beautiful sunset over the ocean with gentle waves",
"callback": "https://your-callback-url.com"
}'
# 基于图像生成视频
curl -X POST "https://ali.youchuan.cn/v1/tob/video-diffusion" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "existing_job_id",
"imageNo": 0,
"prompt": "Make this image move with gentle animation",
"callback": "https://your-callback-url.com"
}'// 文本生成视频
fetch('https://ali.youchuan.cn/v1/tob/video-diffusion', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
prompt: 'A beautiful sunset over the ocean with gentle waves',
callback: 'https://your-callback-url.com'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
// 基于图像生成视频
fetch('https://ali.youchuan.cn/v1/tob/video-diffusion', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: 'existing_job_id',
imageNo: 0,
prompt: 'Make this image move with gentle animation',
callback: 'https://your-callback-url.com'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "d0e1f2a3-b4c5-6789-3456-890123456789", "comment": "JobStatusCreated", "videoUrls": [], "cost": 0}任务完成后(返回视频 URL 列表):
{ "jobId": "d0e1f2a3-b4c5-6789-3456-890123456789", "comment": "JobStatusSuccess", "videoUrls": [ "https://cdn.youchuan.cn/attachments/xxxxx/video_0.mp4", "https://cdn.youchuan.cn/attachments/xxxxx/video_1.mp4", "https://cdn.youchuan.cn/attachments/xxxxx/video_2.mp4", "https://cdn.youchuan.cn/attachments/xxxxx/video_3.mp4" ], "cost": 2.4}视频延长
扩展已生成视频的时长,每次延长增加 4 秒。关于运动强度、循环等视频参数请参见 视频高级控制。
请求路径: POST /v1/tob/extend-video
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始视频任务 ID |
videoNo | Integer | 是 | 视频编号 |
prompt | String | 是 | 延长部分的描述提示词 |
callback | String | 否 | 异步回调地址 |
注意 最多可延长 4 次,即生成最长 21 秒的视频(5 + 4×4)。
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/extend-video"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "existing_job_id",
"videoNo": 0,
"prompt": "Continue with more dynamic movement and effects", # 必填参数
"callback": "https://your-callback-url.com"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/extend-video"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "existing_job_id",
"videoNo": 0,
"prompt": "Continue with more dynamic movement and effects", // 必填参数
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"existing_job_id\",\"videoNo\":0,\"prompt\":\"Continue with more dynamic movement and effects\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/extend-video"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/extend-video" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "existing_job_id",
"videoNo": 0,
"prompt": "Continue with more dynamic movement and effects",
"callback": "https://your-callback-url.com"
}'fetch('https://ali.youchuan.cn/v1/tob/extend-video', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: 'existing_job_id',
videoNo: 0,
prompt: 'Continue with more dynamic movement and effects', // 必填参数
callback: 'https://your-callback-url.com'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "f2a3b4c5-d6e7-8901-5678-012345678901", "comment": "JobStatusCreated", "videoUrls": [], "cost": 0}视频高清
将视频提升至 1080P 分辨率。
请求路径: POST /v1/tob/video-upscale
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 原始视频任务 ID |
videoNo | Integer | 是 | 视频编号 |
callback | String | 否 | 异步回调地址 |
注意 目前仅支持高清为 1080P 视频。
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/video-upscale"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "existing_job_id",
"videoNo": 0,
"type": 0
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/video-upscale"
headers := map[string]string{
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY",
}
data := map[string]interface{}{
"jobId": "existing_job_id",
"videoNo": 0,
"type": 0,
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
for key, value := range headers {
req.Header.Set(key, value)
}
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"existing_job_id\",\"videoNo\":0,\"type\":0}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/video-upscale"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/video-upscale" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "existing_job_id",
"videoNo": 0,
"type": 0
}'fetch('https://ali.youchuan.cn/v1/tob/video-upscale', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: 'existing_job_id',
videoNo: 0,
type: 0
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "jobId": "f2a3b4c5-d6e7-8901-5678-012345678901", "comment": "JobStatusCreated", "videoUrls": [], "cost": 0}账户管理接口
查询任务信息
获取指定任务的详细信息和状态。
请求路径: GET /v1/tob/job/{jobId}
代码示例
import requests
job_id = "12345"
url = f"https://ali.youchuan.cn/v1/tob/job/{job_id}"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
response = requests.get(url, headers=headers)
print(response.json())package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
jobId := "12345"
url := fmt.Sprintf("https://ali.youchuan.cn/v1/tob/job/%s", jobId)
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String jobId = "12345";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/job/" + jobId))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X GET "https://ali.youchuan.cn/v1/tob/job/12345" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY"fetch('https://ali.youchuan.cn/v1/tob/job/12345', {
method: 'GET',
headers: {
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200)—— 图像任务:
{ "jobId": "d4f7a2b1-8e3c-4f5a-9b6d-1234567890ab", "comment": "JobStatusSuccess", "text": "A beautiful sunset over the mountains --ar 16:9", "urls": [ "https://cdn.youchuan.cn/attachments/xxxxx/image_0.png", "https://cdn.youchuan.cn/attachments/xxxxx/image_1.png", "https://cdn.youchuan.cn/attachments/xxxxx/image_2.png", "https://cdn.youchuan.cn/attachments/xxxxx/image_3.png" ], "cost": 0.6, "createdAt": "2025-03-15T10:30:00Z", "finishedAt": "2025-03-15T10:30:45Z"}成功响应(200)—— 视频任务:
{ "jobId": "d0e1f2a3-b4c5-6789-3456-890123456789", "comment": "JobStatusSuccess", "videoUrls": [ "https://cdn.youchuan.cn/attachments/xxxxx/video_0.mp4" ], "cost": 2.4, "createdAt": "2025-03-15T11:00:00Z", "finishedAt": "2025-03-15T11:02:30Z"}错误响应(401):
{ "code": 401, "message": "Invalid_App_Identifier", "reason": "无效的机构标识"}查询消耗历史
获取账户的消费历史记录,支持分页和时间范围过滤。
请求路径: GET /v1/tob/costs
请求参数:
参数 | 类型 | 必填 | 说明 |
pageNo | Integer | 是 | 页码,取值范围 1-1000 |
pageSize | Integer | 是 | 每页数据量,取值范围 1-500 |
since | String | 否 | 起始时间 |
to | String | 否 | 结束时间 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/costs"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
params = {
"pageNo": 1,
"pageSize": 10,
"since": "2023-01-01T00:00:00Z",
"to": "2023-12-31T23:59:59Z"
}
response = requests.get(url, headers=headers, params=params)
print(response.json())package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/costs?pageNo=1&pageSize=10&since=2023-01-01T00:00:00Z&to=2023-12-31T23:59:59Z"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/costs?pageNo=1&pageSize=10&since=2023-01-01T00:00:00Z&to=2023-12-31T23:59:59Z"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X GET "https://ali.youchuan.cn/v1/tob/costs?pageNo=1&pageSize=10&since=2023-01-01T00:00:00Z&to=2023-12-31T23:59:59Z" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY"fetch('https://ali.youchuan.cn/v1/tob/costs?pageNo=1&pageSize=10&since=2023-01-01T00:00:00Z&to=2023-12-31T23:59:59Z', {
method: 'GET',
headers: {
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "data": [ { "jobId": "d4f7a2b1-8e3c-4f5a-9b6d-1234567890ab", "type": "diffusion", "cost": 0.6, "createdAt": "2023-06-15T10:30:00Z", "status": "JobStatusSuccess" }, { "jobId": "a1b2c3d4-5e6f-7a8b-9c0d-abcdef123456", "type": "upscale", "cost": 0.6, "createdAt": "2023-06-15T09:15:00Z", "status": "JobStatusSuccess" } ], "total": 128, "pageNo": 1, "pageSize": 10}月度消耗详情
查看月度消费统计数据。
请求路径: GET /v1/tob/cost-monthly
请求参数:
参数 | 类型 | 必填 | 说明 |
pageNo | Integer | 是 | 页码,取值范围 1-1000 |
pageSize | Integer | 是 | 每页数据量,取值范围 1-500 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/cost-monthly"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
params = {
"pageNo": 1,
"pageSize": 10
}
response = requests.get(url, headers=headers, params=params)
print(response.json())package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/cost-monthly?pageNo=1&pageSize=10"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/cost-monthly?pageNo=1&pageSize=10"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X GET "https://ali.youchuan.cn/v1/tob/cost-monthly?pageNo=1&pageSize=10" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY"fetch('https://ali.youchuan.cn/v1/tob/cost-monthly?pageNo=1&pageSize=10', {
method: 'GET',
headers: {
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "data": [ { "month": "2023-06", "totalCost": 45.6, "totalJobs": 76, "breakdown": { "diffusion": 30.0, "upscale": 9.6, "variation": 6.0 } }, { "month": "2023-05", "totalCost": 38.4, "totalJobs": 64, "breakdown": { "diffusion": 24.0, "upscale": 8.4, "variation": 6.0 } } ], "total": 6, "pageNo": 1, "pageSize": 10}获取账户信息
查询当前订阅状态和剩余资源。
请求路径: GET /v1/tob/subscribe
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/subscribe"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
response = requests.get(url, headers=headers)
print(response.json())package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/subscribe"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/subscribe"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X GET "https://ali.youchuan.cn/v1/tob/subscribe" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY"fetch('https://ali.youchuan.cn/v1/tob/subscribe', {
method: 'GET',
headers: {
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "plan": "professional", "status": "active", "fastTimeRemaining": 120.5, "relaxTimeRemaining": 500.0, "fastTimeTotal": 200.0, "relaxTimeTotal": 500.0, "renewDate": "2023-07-01T00:00:00Z"}回调通知演示
用于测试回调功能。
请求路径: POST /v1/tob/callback
请求参数:
参数 | 类型 | 必填 | 说明 |
jobId | String | 是 | 用于测试的任务 ID |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/callback"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"jobId": "12345"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/callback"
data := map[string]string{
"jobId": "12345",
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"jobId\":\"12345\"}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/callback"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/callback" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"jobId": "12345"
}'fetch('https://ali.youchuan.cn/v1/tob/callback', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
jobId: '12345'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "success": true, "message": "Callback test sent successfully"}Moodboard 接口
创建 Moodboard
创建一个灵感收集板,用于组织和管理参考图像。
请求路径: POST /v1/tob/moodboard
请求参数:
参数 | 类型 | 必填 | 说明 |
name | String | 是 | 收集板名称 |
description | String | 否 | 收集板描述 |
images | Array | 否 | 初始图像列表 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/moodboard"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"name": "我的创意收集",
"description": "收集各种风景图片",
"images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
}
response = requests.post(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/moodboard"
data := map[string]interface{}{
"name": "我的创意收集",
"description": "收集各种风景图片",
"images": []string{"https://example.com/image1.jpg", "https://example.com/image2.jpg"},
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String json = "{\"name\":\"我的创意收集\",\"description\":\"收集各种风景图片\",\"images\":[\"https://example.com/image1.jpg\",\"https://example.com/image2.jpg\"]}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/moodboard"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X POST "https://ali.youchuan.cn/v1/tob/moodboard" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "我的创意收集",
"description": "收集各种风景图片",
"images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
}'fetch('https://ali.youchuan.cn/v1/tob/moodboard', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
name: '我的创意收集',
description: '收集各种风景图片',
images: ['https://example.com/image1.jpg', 'https://example.com/image2.jpg']
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "id": "mb-a1b2c3d4-5e6f-7a8b-9c0d", "name": "我的创意收集", "description": "收集各种风景图片", "images": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg" ], "createdAt": "2023-06-15T10:30:00Z", "updatedAt": "2023-06-15T10:30:00Z"}更新 Moodboard
修改已有的灵感收集板。
请求路径: PUT /v1/tob/moodboard/{id}
请求参数:
参数 | 类型 | 必填 | 说明 |
id | String | 是 | Moodboard ID(路径参数) |
name | String | 否 | 新的收集板名称 |
description | String | 否 | 新的收集板描述 |
images | Array | 否 | 更新的图像列表 |
代码示例
import requests
moodboard_id = "12345"
url = f"https://ali.youchuan.cn/v1/tob/moodboard/{moodboard_id}"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
"name": "更新后的创意收集",
"description": "更新后的风景图片收集",
"images": ["https://example.com/new-image1.jpg", "https://example.com/new-image2.jpg"]
}
response = requests.put(url, headers=headers, json=data)
print(response.json())package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
moodboardId := "12345"
url := fmt.Sprintf("https://ali.youchuan.cn/v1/tob/moodboard/%s", moodboardId)
data := map[string]interface{}{
"name": "更新后的创意收集",
"description": "更新后的风景图片收集",
"images": []string{"https://example.com/new-image1.jpg", "https://example.com/new-image2.jpg"},
}
jsonData, _ := json.Marshal(data)
req, _ := http.NewRequest("PUT", url, bytes.NewBuffer(jsonData))
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String moodboardId = "12345";
String json = "{\"name\":\"更新后的创意收集\",\"description\":\"更新后的风景图片收集\",\"images\":[\"https://example.com/new-image1.jpg\",\"https://example.com/new-image2.jpg\"]}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/moodboard/" + moodboardId))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.header("Content-Type", "application/json")
.PUT(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X PUT "https://ali.youchuan.cn/v1/tob/moodboard/12345" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "更新后的创意收集",
"description": "更新后的风景图片收集",
"images": ["https://example.com/new-image1.jpg", "https://example.com/new-image2.jpg"]
}'fetch('https://ali.youchuan.cn/v1/tob/moodboard/12345', {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
},
body: JSON.stringify({
name: '更新后的创意收集',
description: '更新后的风景图片收集',
images: ['https://example.com/new-image1.jpg', 'https://example.com/new-image2.jpg']
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "id": "mb-a1b2c3d4-5e6f-7a8b-9c0d", "name": "更新后的创意收集", "description": "更新后的风景图片收集", "images": [ "https://example.com/new-image1.jpg", "https://example.com/new-image2.jpg" ], "createdAt": "2023-06-15T10:30:00Z", "updatedAt": "2023-06-16T14:20:00Z"}获取 Moodboard 列表
查询所有灵感收集板,支持分页。
请求路径: GET /v1/tob/moodboards
请求参数:
参数 | 类型 | 必填 | 说明 |
pageNo | Integer | 否 | 页码 |
pageSize | Integer | 否 | 每页数据量 |
代码示例
import requests
url = "https://ali.youchuan.cn/v1/tob/moodboards"
headers = {
"x-youchuan-app": "YOUR_APP_ID",
"x-youchuan-secret": "YOUR_SECRET_KEY"
}
params = {
"pageNo": 1,
"pageSize": 10
}
response = requests.get(url, headers=headers, params=params)
print(response.json())package main
import (
"fmt"
"io/ioutil"
"net/http"
)
func main() {
url := "https://ali.youchuan.cn/v1/tob/moodboards?pageNo=1&pageSize=10"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("x-youchuan-app", "YOUR_APP_ID")
req.Header.Set("x-youchuan-secret", "YOUR_SECRET_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
fmt.Println(string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://ali.youchuan.cn/v1/tob/moodboards?pageNo=1&pageSize=10"))
.header("x-youchuan-app", "YOUR_APP_ID")
.header("x-youchuan-secret", "YOUR_SECRET_KEY")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}curl -X GET "https://ali.youchuan.cn/v1/tob/moodboards?pageNo=1&pageSize=10" \
-H "x-youchuan-app: YOUR_APP_ID" \
-H "x-youchuan-secret: YOUR_SECRET_KEY"fetch('https://ali.youchuan.cn/v1/tob/moodboards?pageNo=1&pageSize=10', {
method: 'GET',
headers: {
'x-youchuan-app': 'YOUR_APP_ID',
'x-youchuan-secret': 'YOUR_SECRET_KEY'
}
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));响应示例
成功响应(200):
{ "data": [ { "id": "mb-a1b2c3d4-5e6f-7a8b-9c0d", "name": "创意收集 A", "description": "风景图片", "imageCount": 12, "createdAt": "2023-06-15T10:30:00Z" }, { "id": "mb-e5f6a7b8-9c0d-1e2f-3a4b", "name": "创意收集 B", "description": "人物肖像", "imageCount": 8, "createdAt": "2023-06-10T08:00:00Z" } ], "total": 5, "pageNo": 1, "pageSize": 10}错误码
所有接口在出现错误时,返回如下统一结构:
{ "code": 500, "message": "失败详细描述", "reason": "失败原因"}错误码列表
错误码 | 错误标识 | 说明 |
400 | Invalid_Argument | 请求参数无效 |
400 | Invalid_Prompt_Parameter | 提示词参数格式错误 |
400 | Cancel_Job_Not_Running | 无法取消非执行中的任务 |
401 | Invalid_App_Identifier | 无效的机构标识(x-youchuan-app 错误) |
402 | No_More_Relax_Credit | 慢速模式额度已用完 |
402 | Account_Fee_Not_Enough | 账户余额不足 |
403 | Permission_Denied | 权限不足 |
403 | Msg_Sensitive | 提示词包含敏感内容,触发合规审核 |
403 | Relax_Not_Allow | 不允许使用慢速模式 |
405 | Not_Support | 当前操作不支持 |
429 | Max_Concurrent_Limited | 并发请求数达到上限 |
500 | Internal_Server_Error | 服务器内部错误 |
503 | Server_Busy | 服务器繁忙,请稍后重试 |
503 | Request_Timeout | 请求超时 |
任务状态
任务响应中的 comment 字段标识当前任务状态:
comment 字段返回值 | 说明 |
JobStatusCreated | 已创建 |
JobStatusRunning | 执行中 |
JobStatusSuccess | 成功 |
JobStatusFail | 未知错误 |
JobStatusError | 执行报错 |
JobStatusReject | 图片审核未通过 |
JobStatusTextReject | 文本审核未通过(生成失败的任务不消耗任务额度) |
JobStatusBadPrompt | 提示词格式错误(生成失败的任务不消耗任务额度) |
JobStatusInvalidParameter | 提示词格式错误,请重试(生成失败的任务不消耗任务额度) |
JobStatusTimeout | 任务失败(超时) |
JobStatusRequestTimeout | 任务处理失败(超时) |
JobStatusInvalidImagePromptLink | 无效图片链接或获取图片超时,请修改链接或重试 |
JobStatusMaxConcurrentLimited | 您已达到同时任务数上限 |
JobStatusCreditNotEnough | 您当前任务额度已用完,请升级计划或者购买更多任务额度 |
JobStatusCanceled | 任务已经取消 |
JobStatusQueued | 排队中 |
JobStatusImagePromptDenied | 图片prompt敏感 |
JobStatusDuplicateImage | 存在重复图片 |