接入必读
/
开放接口
Last updated

开放接口

悠船开放API提供图片生成、视频生成、帐户管理、moodboard4大类接口；

注意事项

  • 高级编辑/转绘：涉及高级编辑或转绘的任务仅支持"高清"操作

  • 授权信息: 每次接口调用均需要API授权信息，具体请参照 授权说明

  • OpenAPI: OpenAPI格式接口定义文档 下载请点击

图片生成

接口分为 直接生成 和 二次编辑2类；直接生成是指只需要提供提示词等必须的参数，可以直接生成图片；二次编辑是指需要提供前一个任务ID和图片编号来执行图片生成。

接口名称接口地址分类功能描述
文生图/v1/tob/diffusion直接生成通过文本描述生成图像
变化/v1/tob/variation二次编辑生成与原图相似但具有一定变化的图像
高清/v1/tob/upscale二次编辑提升图像质量和分辨率
重新执行任务/v1/tob/reroll二次编辑使用相同参数重新生成图像
延展/v1/tob/pan二次编辑向指定方向延展图像
扩图/v1/tob/outpaint二次编辑向所有方向同时扩展图像
区域重绘/v1/tob/inpaint二次编辑重新生成图像中的特定区域
重塑/v1/tob/remix二次编辑使用新的提示词调整图像
编辑/v1/tob/edit二次编辑在画布上编辑现有图像
高级编辑/v1/tob/upload-paint直接生成上传图像并进行高级编辑
转绘/v1/tob/retexture直接生成改变图像的纹理风格
移除背景/v1/tob/remove-background直接生成自动去除图像背景
增强/v1/tob/enhance二次编辑增强图片质量,仅支持draft类型任务

文生图 (Diffusion)

  • 接口: /v1/tob/diffusion
  • 方法: POST
  • 描述: 通过文本描述生成图像
  • 请求参数:
    • text: 文本信息，长度[1-8192]（必填）
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
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())

变化 (Variation)

  • 接口: /v1/tob/variation
  • 方法: POST
  • 描述: 生成与原图相似但具有一定变化的图像
  • 请求参数:
    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • type: 变换类型（必填）：0:轻微变换(subtle), 1:强烈变换(strong)
    • callback: 任务结果回调通知接口（可选）
    • remixPrompt: 新提示词, 长度[1-8192]（可选）
  • 错误码:
    • 405: 高级编辑/转绘任务仅支持高清
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())

高清 (Upscale)

  • 接口: /v1/tob/upscale
  • 方法: POST
  • 描述: 提升图像质量和分辨率
  • 请求参数:
    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • type: 高清类型（必填）：0:标准高清, 1:创意高清, 2:v5_2x, 3:v5_4x
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: 高清任务不支持此操作
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
import requests

url = "https://ali.youchuan.cn/v1/tob/upscale"
headers = {
    "x-youchuan-app": "YOUR_APP_ID",
    "x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
    "jobId": "12345",
    "imageNo": 0,
    "type": 0
}

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

重新执行任务 (Reroll)

  • 接口: /v1/tob/reroll
  • 方法: POST
  • 描述: 使用相同参数重新生成图像
  • 请求参数:
    • jobId: 任务ID（必填）
import 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())

延展 (Pan)

  • 接口: /v1/tob/pan
  • 方法: POST
  • 描述: 向指定方向延展图像
  • 请求参数:
    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • direction: 延展方向（必填）：0:向下(bottom), 1:向右(right), 2:向上(top), 3:向左(left)
    • scale: 延展目标比例，取值范围[1.1-3.0]（必填）
    • remixPrompt: 延展区域提示词, 长度[1-8192]（可选）
    • callback: 任务结果回调通知接口（可选）
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())

扩图 (Outpaint)

  • 接口: /v1/tob/outpaint
  • 方法: POST
  • 描述: 向所有方向同时扩展图像
  • 请求参数:
    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • scale: 扩图目标比例，取值范围[1.1-2.0]（必填）
    • remixPrompt: 扩图区域提示词, 长度[1-8192]（可选）
    • callback: 任务结果回调通知接口（可选）
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())

区域重绘 (Inpaint)

  • 接口: /v1/tob/inpaint

  • 方法: POST

  • 描述: 重新生成图像中的特定区域

  • 请求参数:

    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • mask: 绘制区域（必填），支持多区域重绘(areas或url 2种方式选1种指定绘制区域)
      • areas: 多边形区域(支持指定多个区域)
      • url: 以黑白2值图片指定多边形区域(白色区域为重绘区)
    • remixPrompt: 重绘区域提示词, 长度[1-8192]（可选）
    • callback: 任务结果回调通知接口（可选）

  • 参数说明

    • mask.areas参数以数组的形式支持一次指定多个绘制区域，width/height为原图片像素大小
    • mask.areas[].points为多边形顶点坐标，以左上为原点，按照xy的格式、以顺时针方式依次排列，例如顶点(1,1)(100,1)(100,100)(1,100)对应的points为[1,1,100,1,100,100,1,100]
    • mask.url为一张宽高与原图大小一致的黑白图片，白色区域为重绘区域
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())

重塑 (Remix)

  • 接口: /v1/tob/remix
  • 方法: POST
  • 描述: 使用新的提示词调整图像
  • 请求参数:
    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • remixPrompt: 新提示词, 长度[1-8192]（必填）
    • mode: remix模式（可选）：0:强烈调整(strong), 1:细微调整(subtle)，默认为强烈模式
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
import requests

url = "https://ali.youchuan.cn/v1/tob/remix"
headers = {
    "x-youchuan-app": "YOUR_APP_ID",
    "x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
    "jobId": "12345",
    "imageNo": 0,
    "remixPrompt": "Change style to watercolor painting",
    "mode": 0
}

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

编辑 (Edit)

  • 接口: /v1/tob/edit
  • 方法: POST
  • 描述: 在画布上编辑现有图像
  • 请求参数:
    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • canvas: 画布对象（必填）
      • width: 像素宽
      • height: 像素高
    • imgPos: 图片相对画布的坐标及大小（必填）
      • width: 像素宽
      • height: 像素高
      • x: 相对画布左上角水平位移
      • y: 相对画布左上角垂直位移
    • remixPrompt: 提示词（必填）
    • mask: 原图重绘区域（可选），areas或url 2种方式选1种指定绘制区域
      • areas: 多边形区域(支持指定多个区域)
      • url: 以黑白2值图片指定多边形区域(白色区域为重绘区)
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
  • 参数说明
    • mask.areas参数以数组的形式支持一次指定多个绘制区域，width/height为原图片像素大小
    • mask.areas[].points为多边形顶点坐标，以左上为原点，按照xy的格式、以顺时针方式依次排列，例如顶点(1,1)(100,1)(100,100)(1,100)对应的points为[1,1,100,1,100,100,1,100]
    • mask.url为一张宽高与原图大小一致的黑白图片，白色区域为重绘区域
    • imgPos用于指定图片在画布上的位置和大小
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())

高级编辑 (Uploadpaint)

  • 接口: /v1/tob/upload-paint
  • 方法: POST
  • 描述: 上传图像并进行高级编辑
  • 请求参数:
    • imgUrl: 图片url, 长度[1-1024]（必填）
    • mask: 原图重绘区域（必填），areas或url 2种方式选1种指定绘制区域
      • areas: 多边形区域(支持指定多个区域)
      • url: 以黑白2值图片指定多边形区域(白色区域为重绘区)
    • canvas: 画布对象（必填）
      • width: 像素宽
      • height: 像素高
    • imgPos: 图片相对画布的坐标及大小（必填）
      • width: 像素宽
      • height: 像素高
      • x: 相对画布左上角水平位移
      • y: 相对画布左上角垂直位移
    • remixPrompt: 提示词（必填）
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
  • 参数说明
    • mask.areas参数以数组的形式支持一次指定多个绘制区域，width/height为原图片像素大小
    • mask.areas[].points为多边形顶点坐标，以左上为原点，按照xy的格式、以顺时针方式依次排列，例如顶点(1,1)(100,1)(100,100)(1,100)对应的points为[1,1,100,1,100,100,1,100]
    • mask.url为一张宽高与原图大小一致的黑白图片，白色区域为重绘区域
    • imgPos用于指定图片在画布上的位置和大小
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())

转绘 (Retexture)

  • 接口: /v1/tob/retexture
  • 方法: POST
  • 描述: 改变图像的纹理风格
  • 请求参数:
    • imgUrl: 图片url, 长度[1-1024]（必填）
    • remixPrompt: 提示词，目前只支持6.1及以上的模型（必填）
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
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())

移除背景 (Remove Background)

  • 接口: /v1/tob/remove-background
  • 方法: POST
  • 描述: 自动去除图像背景
  • 请求参数:
    • imgUrl: 图片url（必填）
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
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())

增强 (Enhance)

  • 接口: /v1/tob/enhance
  • 方法: POST
  • 描述: 增强图片质量(仅支持draft类型任务)
  • 请求参数:
    • jobId: 任务ID（必填）
    • imageNo: 图片编号(0/1/2/3)（必填）
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
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())

视频生成

接口用于根据文本描述或图像生成短视频内容，支持多种分辨率和扩展功能，视频功能介绍请参考 文档说明

接口名称接口地址分类功能描述
图生视频/v1/tob/video-diffusion直接生成通过文本描述和指定首帧图生成短视频
视频延长/v1/tob/extend-video二次编辑扩展现有视频的时长
视频高清/v1/tob/video-upscale二次编辑提升视频质量和分辨率

图生视频 (Video Diffusion)

  • 接口: /v1/tob/video-diffusion
  • 方法: POST
  • 描述: 基于图像生成短视频，支持多种分辨率选择。jobId/prompt 二选一
  • 请求参数:
    • jobId: 任务ID（可选，用于指定首帧图）
    • imageNo: 图片编号(0/1/2/3)（当提供jobId时使用）
    • prompt: 视频生成提示文本(可通过图片链接指定首帧图)，长度[1-8192]（与jobId二选一）
    • callback: 任务结果回调通知接口（可选），长度[1-2048]
    • videoType: 视频分辨率类型（可选），默认480p
      • 0: 480p
      • 1: 720p
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
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": "https://your-image.com A beautiful sunset over the ocean with gentle waves",
    "callback": "https://your-callback-url.com",
    "videoType": 1  # 720p
}

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",
    "videoType": 0  # 480p
}

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

视频延长 (Extend Video)

  • 接口: /v1/tob/extend-video
  • 方法: POST
  • 描述: 扩展现有视频的时长，最多可扩展4次
  • 请求参数:
    • jobId: 任务ID（必填）
    • videoNo: 视频编号[0/1/2/3]（必填）
    • prompt: 扩展视频的提示文本，长度[1-8192]（必填）
    • callback: 任务结果回调通知接口（可选），长度[1-2048]
  • 错误码:
    • 400: 无效请求参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: Prompt包含敏感词汇
    • 405: 视频最多可扩展4次
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
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())

视频高清 (Video Upscale)

  • 接口: /v1/tob/video-upscale
  • 方法: POST
  • 描述: 生成1080P视频
  • 请求参数:
    • jobId: 任务ID（必填）
    • videoNo: 视频编号[0/1/2/3]（必填）
    • callback: 任务结果回调通知接口（可选）
  • 错误码:
    • 400: 无效Prompt参数
    • 401: 无效App身份
    • 402: 账户余额不足
    • 403: 高清任务不支持此操作
    • 429: 已达当前套餐最大并发
    • 500: 服务器内部错误
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())

帐户管理

接口名称接口地址分类功能描述
查询任务信息/v1/tob/job/{jobId}帐户管理获取特定任务的详情
查询任务消耗历史记录/v1/tob/costs帐户管理获取账户的消费历史
按计费周期列举消耗详情/v1/tob/cost-monthly帐户管理查看月度消费统计
获取当前账户信息/v1/tob/subscribe帐户管理查询账户订阅状态和资源情况
任务回调通知演示/v1/tob/callback帐户管理用于测试回调功能

查询任务信息

  • 接口: /v1/tob/job/{jobId}
  • 方法: GET
  • 描述: 获取特定任务的详情
  • 请求参数:
    • jobId: 任务ID（必填）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 404: 任务不存在
    • 500: 服务器内部错误
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())

查询任务消耗历史记录

  • 接口: /v1/tob/costs
  • 方法: GET
  • 描述: 获取账户的消费历史
  • 请求参数:
    • pageNo: 页码[1-1000]（必填）
    • pageSize: 每页数据量[1-500]（必填）
    • since: 起始时间（可选）
    • to: 结束时间（可选）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 500: 服务器内部错误
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())

按计费周期列举消耗详情

  • 接口: /v1/tob/cost-monthly
  • 方法: GET
  • 描述: 查看月度消费统计
  • 请求参数:
    • pageNo: 页码[1-1000]（必填）
    • pageSize: 每页数据量[1-500]（必填）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 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())

获取当前账户信息

  • 接口: /v1/tob/subscribe
  • 方法: GET
  • 描述: 查询账户订阅状态和资源情况
  • 请求参数: 无
  • 错误码:
    • 401: 无效App身份
    • 403: 无有效套餐
    • 500: 服务器内部错误
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())

任务回调通知演示

  • 接口: /v1/tob/callback
  • 方法: POST
  • 描述: 用于测试回调功能
  • 请求参数:
    • jobId: 用于测试的任务信息（必填）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 500: 服务器内部错误
import requests

url = "https://your-api-route/callback"
headers = {
    "x-youchuan-app": "YOUR_APP_ID",
    "x-youchuan-secret": "YOUR_SECRET_KEY"
}
data = {
    "id": "68be9b50553a97d658968285",
    "text": "A beautiful sunset over the mountains",
    "urls": [
        "https://openapi-youchuan.oss-cn-shanghai.aliyuncs.com/xxxxx_1.png",
        "https://openapi-youchuan.oss-cn-shanghai.aliyuncs.com/xxxxx_2.png",
        "",
        "https://openapi-youchuan.oss-cn-shanghai.aliyuncs.com/xxxxx_4.png",
    ],
    "status": 2,
    "comment": "成功",
    "cost": {
        "jobId": "68be9b50553a97d658968285",
        "fastCost": 1,
        "relaxCost": 0,
        "feeCost": 50,
        "costAt": "2025-09-08T09:01:04.510743Z"
    },
    "audits": [
        "",
        "",
        "涉政",
        ""
    ],
    "seed": 4291795396
}

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

moodboard

灵感收集板(Moodboard)功能允许用户创建和管理图片集合，用于创意项目的视觉参考和灵感收集

接口名称接口地址功能描述
创建Moodboard/v1/tob/moodboard创建灵感收集板
更新Moodboard/v1/tob/moodboard/{id}修改现有的灵感收集板
获取Moodboard列表/v1/tob/moodboards查询所有灵感收集板

创建Moodboard

  • 接口: /v1/tob/moodboard
  • 方法: POST
  • 描述: 创建灵感收集板
  • 请求参数:
    • name: Moodboard名称（必填）
    • description: Moodboard描述（可选）
    • images: 图片列表（可选）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 500: 服务器内部错误
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())

更新Moodboard

  • 接口: /v1/tob/moodboard/{id}
  • 方法: PUT
  • 描述: 修改现有的灵感收集板
  • 请求参数:
    • id: Moodboard ID（必填）
    • name: 新的Moodboard名称（可选）
    • description: 新的Moodboard描述（可选）
    • images: 更新的图片列表（可选）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 404: Moodboard不存在
    • 500: 服务器内部错误
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())

获取Moodboard列表

  • 接口: /v1/tob/moodboards
  • 方法: GET
  • 描述: 查询所有灵感收集板
  • 请求参数:
    • pageNo: 页码（可选）
    • pageSize: 每页数据量（可选）
  • 错误码:
    • 400: 无效参数
    • 401: 无效App身份
    • 500: 服务器内部错误
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())

错误描述

接口请求失败时，我们会返回失败信息，示例结构如下:

{ "code": 500, "message": "失败详细描述", "reason": "失败原因"}
CodeReasonMessage
500Internal_Server_Error服务器内部错误
400Invalid_Argument无效参数
403Permission_Denied权限不足
503Server_Busy服务器忙碌
503Request_Timout请求处理超时
401Invalid_App_Identifier无效App身份
400Invalid_Prompt_Parameter无效Prompt参数
402No_More_Relax_CreditRelax模式已用完
403Relax_Not_Allow当前套餐不支持Relax模式
429Max_Concurrent_Limited已达当前套餐最大并发
402Account_Fee_Not_Enough账户余额不足
400Cancel_Job_Not_Runnig无法取消非执行中的任务
400Job_ReUpscale_Not_Support高清任务不支持再次高清
403Msg_SensitivePrompt包含敏感词汇
403Upscale_Not_Support高清任务不支持此操作
405Not_Support不支持此操作
403No_Avaliable_Plan无有效套餐