文档

API详情

更新时间:

重要

StableDiffusion文生图模型API目前处于"申请体验"阶段,请点击此处申请。

在您的账号未申请体验或申请未通过时,调用StableDiffusion文生图模型API将返回错误状态码。

StableDiffusion文生图模型

说明

支持的领域/任务:aigc

  • StableDiffusion文生图模型目前针对开源社区的stable-diffusion-v1.5版本和stable-diffusion-xl版本进行了服务化支持。

  • 模型具备的能力:通过文本描述进行图片生成(文生图)。

  • 用户通过输入文本指令prompt、负样指令negative_prompt、尺寸size以及希望生成的数量n,来确定希望生成图片的样式和数量。返回的则是用户根据文本指令需要并避免负样指令的图片。

模型概览

模型名

模型简介

stable-diffusion-xl

stable-diffusion-xl相比于v1.5做了重大的改进,并且与当前为开源的文生图SOTA模型(midjorney)效果相当,具体改进之处包括:更大的unet backbone,是之前的3倍;增加了refinement模块用于改善生成图片的质量;更高效的训练技巧等。

stable-diffusion-v1.5

stable-diffusion-v1.5是用stable-diffusion-v1.2检查点的权重初始化的,并随后在"laion-aesthetics v25+"上以512x512的分辨率进行了595k步的微调,并减少了10%的文本条件化,以提高无分类器的引导采样。

API参考

前提条件

文本生成

以下示例展示了调用StableDiffusion文生图模型对一个用户指令进行响应的代码。

说明

需要使用您的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

model = "stable-diffusion-xl"
prompt = "Eagle flying freely in the blue sky and white clouds"


def sample_block_call():
    rsp = ImageSynthesis.call(model=model,
                              prompt=prompt,
                              negative_prompt="garfield",
                              n=1,
                              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))


def sample_async_call():
    rsp = ImageSynthesis.async_call(model=model,
                                    prompt=prompt,
                                    negative_prompt="garfield",
                                    n=1,
                                    size='512*512')
    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))
    status = ImageSynthesis.fetch(rsp)
    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))

    rsp = ImageSynthesis.wait(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))


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

import java.io.IOException;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Map;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public class Main {
  private static final OkHttpClient CLIENT = new OkHttpClient();
  private static final String MODEL = "stable-diffusion-xl";
  private static final String PROMPT = "Eagle flying freely in the blue sky and white clouds";
  private static final String SIZE = "1024*1024";

  public static void basicCall() throws ApiException, NoApiKeyException, IOException {
    ImageSynthesis is = new ImageSynthesis();
    ImageSynthesisParam param =
        ImageSynthesisParam.builder()
            .model(Main.MODEL)
            .n(1)
            .size(Main.SIZE)
            .prompt(Main.PROMPT)
            .negativePrompt("garfield")
            .build();

    ImageSynthesisResult result = is.call(param);
    System.out.println(result);
    // save image to local files.
    for(Map<String, String> item :result.getOutput().getResults()){
      String paths = new URL(item.get("url")).getPath();
      String[] parts = paths.split("/");
      String fileName = parts[parts.length-1];
      Request request = new Request.Builder()
        .url(item.get("url"))
        .build();

      try (Response response = CLIENT.newCall(request).execute()) {
        if (!response.isSuccessful()) {
          throw new IOException("Unexpected code " + response);
        }

        Path file = Paths.get(fileName);
        Files.write(file, response.body().bytes());
      }
      
    }
  }

  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();
    }catch(ApiException|NoApiKeyException | IOException e){
      System.out.println(e.getMessage());
    }
    System.exit(0);
  }
}



参数说明

参数

类型

默认值

说明

model

string

-

指定用于对话的StableDiffusion文生图模型名,目前仅支持stable-diffusion-xl,stable-diffusion-v1.5。

prompt

string

-

用户当前输入的期望模型生成的文本信息。只支持英文words,不超过75个词。

negative_prompt(可选)

string

""

用户当前输入的不期望模型生成所包含的文本信息。只支持英文words,不超过75个词。

steps(可选)

int

50

去噪推理步数,一般步数越大,图像质量越高,步数越小,推理速度越快。目前默认50,用户可以在1-500间进行调整。

scale(可选)

int

10

用于指导生成的结果与用户输入的prompt的贴合程度,越高则生成结果与用户输入的prompt更相近。目前默认10,用户可以在1-15之间进行调整。

size(可选)

string

stable-difussion-v1.5:"512*512"

stable-difussion-xl: "1024*1024"

图片宽高比,stable-difussion-v1.5的size固定为512*512,stable-difussion-xl的值可支持长宽在512和1024之间以128步长取值的任意组合,如512*1024,1024*768等,默认为1024*1024。

n(可选)

int

4

期望生成图片的数量。

返回结果

  • 返回结果示例

    # python result
    {
        "status_code": 200,
        "request_id": "ea8bfe77-2f35-9df3-ba47-7e05e917b3df",
        "code": null,
        "message": "",
        "output": {
            "task_id": "dea97660-9651-4e6b-a9c3-8afb325b28d0",
            "task_status": "SUCCEEDED",
            "results": [
                {
                    "url": "url1"
                }
            ],
            "task_metrics": {
                "TOTAL": 1,
                "SUCCEEDED": 1,
                "FAILED": 0
            }
        },
        "usage": {
            "image_count": 1
        }
    }
  • 返回参数说明

    返回参数

    类型

    说明

    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

    任务状态:

    • SUCCESSED:任务执行成功

    • FAILED:任务执行失败

    • CANCELED:任务被取消

    • PENDING:任务排队中

    • SUSPENDED:任务挂起

    • RUNNING:任务处理中

    results

    list

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

    task_metrics

    dict

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

    usage

    dict

    image_count用于计量的图片个数。

状态码说明

DashScope灵积模型服务通用状态码请查阅:返回状态码说明

HTTP调用接口

功能描述

StableDiffusion文生图模型需要相对较长的算法调用时间,所以在接口层面采用了异步调用的方式进行任务提交,在通过任务接口提交作业之后,系统会返回对应的作业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。

Bearer d1**2a

X-DashScope-Async

String

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

enable

Body

model

String

指明需要调用的模型,可选择stable-diffusion-xl或者stable-diffusion-v1.5。

stable-diffusion-xl

input.prompt

String

文本内容,仅支持英文,不得超过75个单词,超过部分会自动截断。

a running cat

input.negative_prompt

String

负向文本内容,仅支持英文。

yellow cat

parameters.size

String

生成图像的分辨率,stable-difussion-v1.5的size固定为512*512,stable-difussion-xl的值可支持长宽在512和1024之间以128步长取值的任意组合,如512*1024,1024*768等,默认1024*1024。

512*512

parameters.n

Integer

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

4

parameters.steps

Integer

去噪推理步数,一般步数越大,图像质量越高,步数越小,推理速度越快。目前默认50,用户可以在1-500间进行调整。

40

parameters.scale

Integer

用于指导生成的结果与用户输入的prompt的贴合程度,越高则生成结果与用户输入的prompt更相近。目前默认10,用户可以在1-15之间进行调整。

3

parameters.seed

Integer

图片生成时候的种子值,如果不提供,则算法自动用一个随机生成的数字作为种子,如果给定了,则根据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命令来调用Stable Diffusion模型的脚本。

说明

需要使用您的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": "stable-diffusion-xl",
    "input": {
        "prompt": "a running cat",
        "negative_prompt": "yellow cat"
    },
    "parameters": {
        "size": "512*512",
        "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命令来调用Stable Diffusion模型的脚本。

说明

需要使用您的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
        }
    }
}

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

如果作业执行完成并成功之后,再次查询作业状态,接口将在告知作业状态的同时,一并将作业的结果返回。对于Stable Diffusion,作业在结束之后的状态会持续保留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
    }
}

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

在一次提交中,Stable Diffusion可以根据客户的需求生成多张图片,只要其中一张图片生成成功,作业将被设置为成功状态,并且对应的作业结果会在查询的时候返回,对于失败的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
        }
    }
}

状态码说明

DashScope灵积模型服务通用状态码请查阅:返回状态码说明