API详情

StableDiffusion文生图模型

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

• 模型具备的能力：通过文本描述进行图片生成（文生图）。

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

模型概览

API参考

前提条件

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

• 已安装SDK：安装DashScope SDK。

文本生成

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

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

参数说明

返回结果

• 返回结果示例

  # 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

入参描述

出参描述

请求示例

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

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}

入参描述

出参描述

请求示例

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

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