悠船 API 接口参考

更新时间:
复制为 MD 格式

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

存在重复图片