文本生成图像API详情

通义万相

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

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

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

• 支持中英文双语输入。

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

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

• 参考内容：

  

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

• 参考风格：

  

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

应用场景

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

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

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

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

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

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

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

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

特色优势

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

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

模型概览

输入限制

参考图输入限制：

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

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

• 图像分辨率：大于256×256像素，小于4096×4096像素。

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

前提条件

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

• 已安装最新版SDK：安装DashScope SDK

设置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);
  }
}

参数配置

返回结果

• 返回结果示例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

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

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

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

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

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

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

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

{
    "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通用状态码请查阅：返回状态码说明。