StableDiffusion文生圖模型

• StableDiffusion文生圖模型目前針對開源社區(qū)的stable-diffusion-v1.5版本和stable-diffusion-xl版本進行了服務化支持。

• 模型具備的能力：通過文本描述進行圖片生成（文生圖）。

• 用戶通過輸入文本指令prompt、負樣指令negative_prompt、尺寸size以及希望生成的數(shù)量n，來確定希望生成圖片的樣式和數(shù)量。返回的則是用戶根據(jù)文本指令需要并避免負樣指令的圖片。

模型概覽

API參考

前提條件

• 已開通服務并獲得api-key：API-KEY的獲取與配置。

• 已安裝SDK：安裝DashScope SDK。

文本生成

以下示例展示了調(diào)用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);
  }
}

參數(shù)說明

返回結果

• 返回結果示例

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

• 返回參數(shù)說明

  返回參數(shù)	類型	說明
  status_code	int	200（HTTPStatus.OK）表示請求成功，否則表示請求失敗，可以通過code獲取錯誤碼，通過message字段獲取錯誤詳細信息。
  request_Id	string	系統(tǒng)生成的標志本次調(diào)用的id。
  code	string	表示請求失敗，表示錯誤碼，成功忽略。
  message	string	失敗，表示失敗詳細信息，成功忽略。
  output	dict	調(diào)用結果信息，對于千問模型，包含輸出text。
  task_id	string	異步任務id。
  task_status	string	任務狀態(tài)： SUCCESSED：任務執(zhí)行成功 FAILED：任務執(zhí)行失敗 CANCELED：任務被取消 PENDING：任務排隊中 SUSPENDED：任務掛起 RUNNING：任務處理中
  results	list	生成結果，每個元素為生成圖片的url。
  task_metrics	dict	任務結果信息，TOTAL期望生成數(shù)量，SUCCEEDED成功生成數(shù)量，F(xiàn)AILED失敗數(shù)量。
  usage	dict	image_count用于計量的圖片個數(shù)。

狀態(tài)碼說明

DashScope通用狀態(tài)碼請查閱：返回狀態(tài)碼說明。

HTTP調(diào)用接口

功能描述

StableDiffusion文生圖模型需要相對較長的算法調(diào)用時間，所以在接口層面采用了異步調(diào)用的方式進行任務提交，在通過任務接口提交作業(yè)之后，系統(tǒng)會返回對應的作業(yè)ID，隨后客戶可以通過對應的異步作業(yè)查詢接口獲取任務的狀態(tài)并且在作業(yè)到達最終完成態(tài)后取回對應的作業(yè)結果。

前提條件

已開通服務并獲得API-KEY：API-KEY的獲取與配置。

作業(yè)提交接口調(diào)用

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

入?yún)⒚枋?/b>

出參描述

請求示例

以下示例展示通過CURL命令來調(diào)用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"
}

異常響應示例

在提交作業(yè)請求出錯的情況下，輸出的結果中會通過code和message指明出錯原因。

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

作業(yè)任務狀態(tài)查詢和結果獲取接口

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

入?yún)⒚枋?/b>

出參描述

請求示例

以下示例展示通過CURL命令來調(diào)用Stable Diffusion模型的腳本。

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

響應示例（作業(yè)執(zhí)行中）

作業(yè)提交后將處于排隊狀態(tài)，在得到調(diào)度之后將轉(zhuǎn)為運行狀態(tài)，此時作業(yè)的狀態(tài)為RUNNING，task_metrics將給出具體batch狀態(tài)；

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

響應示例（作業(yè)成功執(zhí)行完畢）

如果作業(yè)執(zhí)行完成并成功之后，再次查詢作業(yè)狀態(tài)，接口將在告知作業(yè)狀態(tài)的同時，一并將作業(yè)的結果返回。對于Stable Diffusion，作業(yè)在結束之后的狀態(tài)會持續(xù)保留24小時以備客戶隨時查詢，24小時之后，作業(yè)將從系統(tǒng)中清除，相關的結果也將一并清除；對應的，作業(yè)生成結果為圖像的URL地址，出于安全考慮，該URL的下載有效期也是24小時，需要用戶在獲取作業(yè)結果后根據(jù)需要及時使用或者轉(zhuǎn)存。

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

響應示例（作業(yè)成功執(zhí)行完畢，部分失敗）

在一次提交中，Stable Diffusion可以根據(jù)客戶的需求生成多張圖片，只要其中一張圖片生成成功，作業(yè)將被設置為成功狀態(tài)，并且對應的作業(yè)結果會在查詢的時候返回，對于失敗的batch，結果中也會返回對應的失敗原因；同時在usage計量中，只會對成功的結果計數(shù)。

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

響應示例（作業(yè)失敗）

如果因為某種原因作業(yè)失敗，則作業(yè)狀態(tài)會設置為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
        }
    }
}

狀態(tài)碼說明

DashScope通用狀態(tài)碼請查閱：返回狀態(tài)碼說明。