文档

文本生成图像API详情

更新时间:
一键部署

通义万相

说明

支持的领域 / 任务:aigc /文生图

通义万相-文本生成图像是基于自研的Composer组合生成框架的AI绘画创作大模型,能够根据用户输入的文字内容,生成符合语义描述的不同风格的图像。通过知识重组与可变维度扩散模型,加速收敛并提升最终生成图片的效果, 结果自然、细节丰富。支持中英文双语输入。

当前模型支持的风格包括但不限于:

水彩、油画、中国画、素描、扁平插画、二次元、3D卡通

模型概览

模型名

模型简介

wanx-v1

通义万相-文本生成图像大模型,支持中英文双语输入,重点风格包括但不限于水彩、油画、中国画、素描、扁平插画、二次元、3D卡通

SDK使用

前提条件

本模型请求处理时间较长,服务采用异步方式提供,SDK进行了封装,您既可以按异步方式调用,也可以按照同步方式调用。

说明

接口限制:对单账户(含主账号与RAM子账号)任务下发接口限制QPS为2,并发任务数量限制为1。

设置API-KEY

 export DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY

同步调用模式

from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis


def simple_call():
    prompt = 'Mouse rides elephant'
    rsp = ImageSynthesis.call(model=ImageSynthesis.Models.wanx_v1,
                              prompt=prompt,
                              n=4,
                              size='1024*1024')
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output)
        print(rsp.usage)
        # save file to current directory
        for result in rsp.output.results:
            file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
            with open('./%s' % file_name, 'wb+') as f:
                f.write(requests.get(result.url).content)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    simple_call()
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;

public class Main {
  public static void basicCall() throws ApiException, NoApiKeyException {
    ImageSynthesis is = new ImageSynthesis();
    ImageSynthesisParam param =
        ImageSynthesisParam.builder()
            .model(ImageSynthesis.Models.WANX_V1)
            .n(4)
            .size("1024*1024")
            .prompt("雄鹰自由自在的在蓝天白云下飞翔")
            .build();

    ImageSynthesisResult result = is.call(param);
    System.out.println(result);
  }

  public static void listTask() throws ApiException, NoApiKeyException {
    ImageSynthesis is = new ImageSynthesis();
    AsyncTaskListParam param = AsyncTaskListParam.builder().build();
    ImageSynthesisListResult result = is.list(param);
    System.out.println(result);
  }

  public void fetchTask() throws ApiException, NoApiKeyException {
    String taskId = "your task id";
    ImageSynthesis is = new ImageSynthesis();
    // If set DASHSCOPE_API_KEY environment variable, apiKey can null.
    ImageSynthesisResult result = is.fetch(taskId, null);
    System.out.println(result.getOutput());
    System.out.println(result.getUsage());
  }

  public static void main(String[] args){
    try{
      basicCall();
      //listTask();
    }catch(ApiException|NoApiKeyException e){
      System.out.println(e.getMessage());
    }
    System.exit(0);
  }
}

  • 参数配置

参数

类型

默认值

说明

model

string

-

指定模型名,目前仅支持 wanx-v1

prompt

string

-

用户当前输入的期望模型执行指令。

n

int

-

期望生成的图片数量,目前限制最多生成4张。

size

string

1024*1024

生成的图片的规格

返回结果

  • 返回结果示例

{
    "status_code": 200,
    "request_id": "b54ffeb8-6212-9dac-808c-b3771cba3788",
    "code": null,
    "message": "",
    "output": {
        "task_id": "996523eb-034d-459b-ac88-b340b95007a4",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "RESULT_URL1"
            },
            {
                "url": "RESULT_URL2"
            },
            {
                "url": "RESULT_URL3"
            },
            {
                "url": "RESULT_URL4"
            }
        ],
        "task_metrics": {
            "TOTAL": 4,
            "SUCCEEDED": 4,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 4
    }
}
  • 返回参数说明

返回参数

类型

说明

status_code

int

200(HTTPStatus.OK)表示请求成功,否则表示请求失败,可以通过code获取错误码,通过message字段获取错误详细信息。

request_Id

string

系统生成的标志本次调用的id。

code

string

表示请求失败,表示错误码,成功忽略。

message

string

失败,表示失败详细信息,成功忽略。

output

dict

调用结果信息,对于千问模型,包含输出text。

task_id

string

异步任务id。

task_status

string

任务状态(SUCCEEDED,FAILED,CANCELED,PENDING,SUSPENDED,RUNNING)

SUCCESSED: 任务执行成功

FAILED: 任务执行失败

CANCELED: 任务被取消

PENDING:任务排队中

SUSPENDED:任务挂起

RUNNING:任务处理中

results

list

生成结果,每个元素为生成图片的url

task_metrics

dict

任务结果信息,TOTAL期望生成数量,SUCCEEDED成功生成数量,FAILED失败数量

usage

dict

image_count用于计量的图片个数

异步调用模式

from http import HTTPStatus

from dashscope import ImageSynthesis


# 创建异步任务
def create_async_task():
    rsp = ImageSynthesis.async_call(model=ImageSynthesis.Models.wanx_v1,
                                    prompt='Eagle flying in blue sky',
                                    n=4,
                                    size='1024*1024')
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output)
        print(rsp.usage)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))
    return rsp


# 获取异步任务信息
def fetch_task_status(task):
    status = ImageSynthesis.fetch(task)
    print(status)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))


# 等待异步任务结束
def wait_task(task):
    rsp = ImageSynthesis.wait(task)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


# 取消异步任务,只有处于PENDING状态的任务才可以取消
def cancel_task(task):
    rsp = ImageSynthesis.cancel(task)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


if __name__ == '__main__':
    task_info = create_async_task()
    fetch_task_status(task_info)
    wait_task(task_info)

异步任务输出

{
    "status_code": 200,
    "request_id": "814762c1-6565-917d-9f6b-bcfa1cc26117",
    "code": "",
    "message": "",
    "output": {
        "task_id": "ea06d3c3-15fa-4487-aee5-348392f4fdcd", # 任务ID
        "task_status": "PENDING", # 任务状态
        "results": []
    },
    "usage": null
}

任务信息输出

{
    "status_code": 200,
    "request_id": "d8811fd1-fc33-9a64-90d8-69cd94051239",
    "code": null,
    "message": "",
    "output": {
        "task_id": "4257e084-30ce-46f1-8f59-5d4d8b3807ec",
        "task_status": "RUNNING",
        "results": [],
        "task_metrics": {
            "TOTAL": 4,
            "SUCCEEDED": 0,
            "FAILED": 0
        }
    },
    "usage": null
}

取消任务输出

取消任务无输出,成功status_code=200

HTTP调用接口

功能描述

本模型需要相对较长的算法调用时间,所以在接口层面采用了异步调用的方式进行任务提交,在通过任务接口提交作业之后,系统会返回对应的作业ID,随后客户可以通过对应的异步作业查询接口获取任务的状态并且在作业到达最终完成态后取回对应的作业结果。

前提条件

作业提交接口调用

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis

入参描述

传参方式

字段

类型

必选

描述

示例值

Header

Content-Type

String

请求类型:application/json

application/json

Authorization

String

API-Key,例如:Bearer d1**2a

Bearer d1**2a

X-DashScope-WorkSpace

String

指明本次调用需要使用的workspace;需要注意的是,对于子账号Apikey调用,此参数为必选项,子账号必须归属于某个workspace才能调用;对于主账号Apikey此项为可选项,添加则使用对应的workspace身份,不添加则使用主账号身份。

ws_QTggmeAxxxxx

X-DashScope-Async

String

固定使用 enable,表明使用异步方式提交作业。

enable

Body

model

String

指明需要调用的模型,固定值wanx-v1

wanx-v1

input.prompt

String

描述画面的提示词信息。支持中英文,长度不超过500个字符,超过部分会自动截断。

一只奔跑的猫

input.negative_prompt

String

画面中不想出现的内容描述词信息。支持中英文,长度不超过500个字符,超过部分会自动截断。

低分辨率、错误、最差质量、低质量、jpeg 伪影、丑陋、重复、病态、残缺、超出框架、多余的手指、变异的手、画得不好的手、画得不好的脸、突变、变形、模糊、脱水、不良的解剖结构、 比例不良、多余肢体、克隆脸、毁容、总体比例、畸形肢体、缺臂、缺腿、多余手臂、多余腿、融合手指、手指过多、长脖子、用户名、水印、签名

parameters.style

String

输出图像的风格,目前支持以下风格取值:

"<auto>" 默认,

"<3d cartoon>" 3D卡通,

"<anime>" 动画,

"<oil painting>" 油画,

"<watercolor>"水彩,

"<sketch>" 素描,

"<chinese painting>" 中国画,

"<flat illustration>" 扁平插画,

"style": "<sketch>"

parameters.size

String

生成图像的分辨率,目前仅支持'1024*1024', '720*1280', '1280*720'三种分辨率,默认为1024*1024像素。

"size": "1024*1024"

parameters.n

Integer

本次请求生成的图片数量,目前支持1~4张,默认为1。

"n": 4

parameters.seed

Integer

图片生成时候的种子值,取值范围为(0,4294967290) 。如果不提供,则算法自动用一个随机生成的数字作为种子,如果给定了,则根据 batch 数量分别生成 seed, seed+1, seed+2, seed+3 为参数的图片。

42

出参描述

字段

类型

描述

示例值

output.task_id

String

本次请求的异步任务的作业 id,实际作业结果需要通过异步任务查询接口获取。

13b1848b-5493-4c0e-8c44-68d038b492af

output.task_status

String

提交异步任务后的作业状态。

PENDING

request_id

String

本次请求的系统唯一码

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

以下示例展示通过CURL命令来调用本模型的脚本

说明

需要使用您的API-KEY替换示例中的 your-dashscope-api-key ,代码才能正常运行。

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "wanx-v1",
    "input": {
        "prompt": "一只奔跑的猫"
    },
    "parameters": {
        "style": "<sketch>", 
        "size": "1024*1024",
        "n":4, 
        "seed":42
    }
}'

响应示例

{
    "output": {
		"task_id": "13b1848b-5493-4c0e-8c44-68d038b492af", 
    	"task_status": "PENDING"
    }
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

异常响应示例

在提交作业请求出错的情况下,输出的结果中会通过 code 和 message 指明出错原因。

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

作业任务状态查询和结果获取接口

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

入参描述

传参方式

字段

类型

必选

描述

示例值

Url Path

task_id

String

需要查询作业的 task_id

13b1848b-5493-4c0e-8c44-68d038b492af

Header

Authorization

String

API-Key,例如:Bearer d1**2a

Bearer d1**2a

出参描述

字段

类型

描述

示例值

output.task_id

String

本次请求的异步任务的作业 id,实际作业结果需要通过异步任务查询接口获取。

13b1848b-5493-4c0e-8c44-68d038b492af

output.task_status

String

被查询作业的作业状态

任务状态:

PENDING 排队中

RUNNING 处理中

SUCCEEDED 成功

FAILED 失败

UNKNOWN 作业不存在或状态未知

usage.task_metrics

Object

作业中每个batch任务的状态:

TOTAL:总batch数目

SUCCEEDED:已经成功的batch数目

FAILED:已经失败的batch数目

"task_metrics":{

"TOTAL":4,

"SUCCEEDED":1,

"FAILED":1

}

usage.image_count

Integer

本次请求成功生成的图片张数

2

request_id

String

本次请求的系统唯一码

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

以下示例展示通过CURL命令来调用本模型的脚本

说明

需要使用您的API-KEY替换示例中的 your-dashscope-api-key ,代码才能正常运行。

curl -X GET \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-af6e-a0c6a421c010

响应示例(作业执行中)

作业提交后将处于排队状态,在得到调度之后将转为运行状态,此时作业的状态为RUNNING,task_metrics将给出具体batch状态;

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":4,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

响应示例(作业成功执行完毕)

如果作业执行完成并成功之后,再次查询作业状态,接口将在告知作业状态的同时,一并将作业的结果返回。对于本模型,作业在结束之后的状态会持续保留24小时以备客户随时查询,24小时之后,作业将从系统中清除,相关的结果也将一并清除;对应的,作业生成的结果为图像的URL地址,出于安全考虑,该URL的下载有效期也是24小时,需要用户在获取作业结果后根据需要及时使用或者转存。

{
    "request_id":"85eaba38-0185-99d7-8d16-4d9135238846",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"SUCCEEDED",
        "results":[
            {
                "url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
            },
            {
                "url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/b2.png
            }
        ],
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":2,
            "FAILED":0
        }
    },
    "usage":{
        "image_count":2
    }
}

响应示例(作业成功执行完毕,部分失败)

在一次提交中,本模型可以根据客户的需求生成多张图片,只要其中一张图片生成成功,作业将被设置为成功状态,并且对应的作业结果会在查询的时候返回,对于失败的batch,结果中也会返回对应的失败原因;同时在usage计量中,只会对成功的结果计数。

    "request_id":"85eaba38-0185-99d7-8d16-4d9135238846",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"SUCCEEDED",
        "results":[
            {
                "url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png
            },
            {
              	"code": "InternalError.Timeout"
								"message": "An internal timeout error has occured during execution, please try again later or contact service support."
            }
        ],
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":1,
            "FAILED":1
        }
    },
    "usage":{
        "image_count":1
    }
}

响应示例(作业失败)

如果因为某种原因作业失败,则作业状态会设置为FAILED,并且通过code和message字段指明错误原因。

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"FAILED",
        "code":"InvalidParameter"
				"message":"The size is not match the allowed size ['1024*1024', '720*1280', '1280*720']"
        "task_metrics":{
            "TOTAL":4,
            "SUCCEEDED":0,
            "FAILED":4
        }
    }
}

状态码说明

大模型服务平台通用状态码请查阅:状态码说明

  • 本页导读 (1)