文档

文本生成图像API详情

更新时间:

通义万相

说明

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

通义万相-文本生成图像是基于自研的Composer组合生成框架的AI绘画创作大模型,能够根据用户输入的文字内容,生成符合语义描述的多样化风格的图像。通过知识重组与可变维度扩散模型,加速收敛并提升最终生成图片的效果,布局自然、细节丰富、画面细腻、结果逼真。AI深度理解中英文文本语义,让文字秒变精致AI画作。

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

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

  • 支持中英文双语输入。

  • 支持客户自定义咒语书/修饰词,可生成不同风格、不同主题、不同派别的图片,满足个性创意的AI图片生成需求。

  • 支持输入参考图片进行参考内容或者参考风格迁移,支持更丰富的风格、主题和派别,AI作画质量更加高保真。

  • 参考内容:

    image.png

    主要参考图片的组成内容。如上图所示,在不改变图片主要内容的情况下可根据文本描述改变参考图的画面风格。

  • 参考风格:

    image.png

    主要参考图片的画面风格。如上图所示,可以将图片的颜色、笔触、材质等作为参考,用来生成同种风格的图像。

应用场景

  • 艺术与设计创作:设计师和创意工作者快速生成概念草图、插画、海报、包装设计、甚至数字艺术品,极大地缩短了构思到成品的时间,降低了创作门槛,文生图技术提供了无限的灵感源泉和高效的原型生成工具。

  • 广告与营销物料生成:文生图能够即时响应广告文案,生成符合品牌调性、产品特性和营销策略的视觉内容,节省了传统拍摄与后期制作的成本,广告内容根据实时热点迅速调整,实现高度定制化和敏捷营销。

  • 教育与培训资源制作:教育工作者和培训师利用文生图模型来创建生动、直观的教学素材,有助于提升教学内容的吸引力和理解度,定制化的图像资源还能用于制作互动课件、电子教科书,丰富教育资源库。

  • 新闻与媒体内容生产:新闻机构和内容平台采用文生图技术来增强报道的视觉呈现,即时生成的视觉内容不仅能吸引读者注意力,提高阅读体验,还能确保新闻报道的时效性和准确性。

  • 游戏与娱乐内容开发:游戏开发者借助文生图大模型来快速生成游戏内的角色、道具、环境元素等美术资源,用于动态生成游戏NPC(非玩家角色)外观或定制化的玩家角色,增加游戏世界的多样性和沉浸感。

  • 室内设计与家居装饰:室内设计师和家居平台利用文生图模型为客户提供虚拟设计方案,可生成相应的空间布局、色彩搭配及装饰细节的三维视图或渲染图,便于设计师快速迭代修改。

  • 时尚与服装设计:时尚设计师和电商平台利用文生图技术进行服装设计和虚拟试穿体验。电商平台则可以结合用户身材数据,让用户输入文字描述想要的服装款式或风格,生成个性化虚拟试穿图片。

  • 图书封面与插图生成:出版社和独立作者利用文生图模型自动生成与书籍主题契合的封面设计和内页插图,模型将创作出引人入胜的封面图像,自动化地为用户提供定制封面选项,简化流程。

特色优势

  • 知识重组&可变维扩散模型:基于自研的Composer组合生成框架的AI绘画创作大模型,通过知识重组与可变维度扩散模型,生成符合语义描述的多样化风格的图像。

  • 效果业界领先:生成图像语义一致性更精准,AI绘画创作布局自然、细节丰富、画面细腻、结果逼真。

模型概览

模型名

模型简介

wanx-v1

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

SDK使用

输入限制

参考图输入限制:

  • 图像格式:JPG、JPEG、PNG、BMP。

  • 图像大小:不超过10 MB。

  • 图像分辨率:大于256×256像素,小于4096×4096像素。

  • URL地址中不能包含中文字符。

前提条件

本模型请求处理时间较长,服务采用异步方式提供,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

integer

-

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

size

string

1024*1024

生成的图片的规格。

返回结果

  • 返回结果示例1:

{
    "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
    }
}
  • 返回结果示例2:示例中看到有这类错误码信息InvalidParameter.DataInspectio会一同和正常没有问题的url一起返回属于正常现象,表示是当前这个提示错误信息的url数据检查错误,媒体格式不支持或不正确,可以重新发起请求再获取一张图片。

{
    "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"
            },
            {
                "code": "InvalidParameter.DataInspection",
                "message": "Unable to download the media resource during the data inspection process."
            },
            {
                "url": "RESULT_URL4"
            }
        ],
        "task_metrics": {
            "TOTAL": 4,
            "SUCCEEDED": 4,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 4
    }
}
  • 返回结果示例3:示例中看到有这类错误码信息DataInspectionFailed会一同和正常的url一起返回属于正常现象,数据检查错误,输出包含疑似敏感内容被绿网拦截。

    {
        "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"
                },
                {
                    "code": "DataInspectionFailed",
                    "message": "Output data may contain inappropriate content."
                },
                {
                    "url": "RESULT_URL3"
                },
                {
                    "url": "RESULT_URL4"
                }
            ],
            "task_metrics": {
                "TOTAL": 4,
                "SUCCEEDED": 4,
                "FAILED": 0
            }
        },
        "usage": {
            "image_count": 4
        }
    }
  • 返回参数说明

    返回参数

    类型

    说明

    status_code

    integer

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

    request_Id

    string

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

    code

    string

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

    message

    string

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

    output

    object

    调用结果信息,对于通义万象模型,包含输出text。

    output.task_id

    string

    异步任务id。

    output.task_status

    string

    任务状态:

    • SUCCEEDED:任务执行成功

    • FAILED:任务执行失败

    • CANCELED:任务被取消

    • PENDING:任务排队中

    • SUSPENDED:任务挂起

    • RUNNING:任务处理中

    output.results

    array

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

    output.task_metrics

    object

    任务结果信息:

    • TOTAL:期望生成数量

    • SUCCEEDED:成功生成数量

    • FAILED:失败数量

    usage

    object

    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
}

HTTP调用接口

功能描述

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

前提条件

已开通服务并获得API-KEY:API-KEY的获取与配置

作业提交接口调用

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

X-DashScope-Async

String

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

enable

Body

model

String

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

wanx-v1

input.prompt

String

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

一只奔跑的猫

input.negative_prompt

String

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

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

input.ref_img

String

输入参考图像的URL;图片格式可为 jpg,png,tiff,webp等常见位图格式。默认为空。

http://xxx/xxx.png

parameters.style

String

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

"<photography>" 摄影,

"<portrait>" 人像写真,

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

"<anime>" 动画,

"<oil painting>" 油画,

"<watercolor>"水彩,

"<sketch>" 素描,

"<chinese painting>" 中国画,

"<flat illustration>" 扁平插画,

"<auto>" 默认

"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

parameters.ref_strength

Float

期望输出结果与垫图(参考图)的相似度,取值范围[0.0, 1.0],数字越大,生成的结果与参考图越相似

0.5

parameters.ref_mode

String

垫图(参考图)生图使用的生成方式,可选值为'repaint' (默认) 和 'refonly'; 其中 repaint代表参考内容,refonly代表参考风格

"repaint"

出参描述

字段

类型

描述

示例值

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,
        "strength": 0.5,
        "ref_mode": "repaint"
    }
}'

响应示例

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

异常响应示例

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

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

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

说明

将您上一步获得的task_id替换以下代码中的{task_id}

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

出参描述

字段

类型

描述

示例值

output.task_id

String

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

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

output.task_status

String

被查询作业的作业状态。

任务状态:

  • PENDING:排队中

  • RUNNING:处理中

  • SUCCEEDED:成功

  • FAILED:失败

  • UNKNOWN:作业不存在或状态未知

output.task_metrics

Object

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

  • TOTAL:总共要生成的图片数目

  • SUCCEEDED:已经生成成功的图片数目

  • FAILED:已经生成失败的图片数目

"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,并且通过codemessage字段指明错误原因。

{
    "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
        }
    }
}

状态码说明

DashScope通用状态码请查阅:返回状态码说明