StableDiffusion3.5 API详情

StableDiffusion文生图模型

说明

支持的领域 / 任务:aigc

调用模型后,因任务排队等原因,可能需要等几分钟才生成结果,此时任务状态为PENDING

相比于Stable Diffusion 1.5 和 Stable Diffusion XL 模型,最新开源的Stable Diffusion 3.5模型在图像质量、文本内容生成、复杂提示理解和资源效率方面有了显著提升。

百炼平台针对开源社区的Stable Diffusion 3.5 Large版本和Stable Diffusion 3.5 Large Turbo版本进行了服务化支持和中文适配。您可以通过配置文本指令prompt 、尺寸size以及希望生成的图片数量n,来确定希望生成图片的样式和数量,并根据需要设置随机种子seed,指定步骤数steps、分类自由引导系数cfg、偏移量shift来确定生成内容的样式和细节。此外,您还可以提供初始图片image及去噪量denoise来进一步控制生成过程。通过灵活配置这些参数,您可以定制生成内容以满足特定需求。

模型概览

模型名

模型简介

stable-diffusion-3.5-large

stable-diffusion-3.5-large是一个具有8亿参数的多模态扩散变压器(MMDiT)文本到图像生成模型,具备卓越的图像质量和提示词匹配度,支持生成100万像素的高分辨率图像,且能够在普通消费级硬件上高效运行。

stable-diffusion-3.5-large-turbo

stable-diffusion-3.5-large-turbo是在stable-diffusion-3.5-large的基础上采用对抗性扩散蒸馏(ADD)技术的模型,具备更快的速度。

前提条件

  • 我们推荐您将API-KEY配置到环境变量中以降低API-KEY的泄漏风险,详情可参考配置API Key到环境变量。您也可以在代码中配置API-KEY,但是泄漏风险会增加。

  • 请在百炼的模型广场找到StableDiffusion模型,点击StableDiffusion模型卡片上的查看详情,并在右上角点击立即申请,申请通过后即可进行模型使用。

通过DashScope SDK调用模型

请您提前安装SDK

代码示例

以下示例展示了调用StableDiffusion3.5文生图模型对一个用户指令进行响应的代码。如果需要调用 Stable Diffusion 3.5 Large Turbo版本只需要用 stable-diffusion-v3.5-large-turbo 替换 stable-diffusion-v3.5-large 即可。

from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os

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

# 同步调用
def sample_block_call():
    rsp = ImageSynthesis.call(model=model,
                              api_key=os.getenv("DASHSCOPE_API_KEY"),
                              prompt=prompt,
                              negative_prompt="garfield",
                              n=1,
                              size='1024*1024')
    if rsp.status_code == HTTPStatus.OK:
        print(rsp)
        # 保存图片到当前文件夹
        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,
                                    api_key=os.getenv("DASHSCOPE_API_KEY"),
                                    prompt=prompt,
                                    negative_prompt="garfield",
                                    n=1,
                                    size='512*512')
    if rsp.status_code == HTTPStatus.OK:
        print(rsp)
    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)
    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.
// 需要安装okhttp依赖

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 com.alibaba.dashscope.utils.JsonUtils;
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-3.5-large";
    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(JsonUtils.toJson(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

-

指明需要调用的模型,可选择stable-diffusion-3.5-large或者stable-diffusion-3.5-large-turbo。

prompt

string

-

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

steps(可选)

integer

40

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

cfg(可选)

double

4.5

用于指导生成的结果与用户输入的prompt的贴合程度,越高则生成结果与用户输入的prompt更相近。目前默认4.5,倾向于输入4~5内的值。

size(可选)

string

1024*1024

生成图像的分辨率,支持长宽在5121024之间以128步长取值的任意组合,如512*1024, 1024*768等, 默认1024*1024。

n (可选)

integer

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": "example_url"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}
  • 返回参数说明

返回参数

类型

说明

status_code

integer

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

request_id

string

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

code

string

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

message

string

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

output

object

调用结果信息,对于千问模型,包含输出text。

task_id

string

异步任务id。

task_status

string

表示任务状态,可选值有:

  • SUCCEEDED:任务执行成功。

  • FAILED: 任务执行失败。

  • CANCELED: 任务被取消。

  • PENDING:任务排队中。

  • SUSPENDED:任务挂起。

  • RUNNING:任务处理中。

results

array

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

task_metrics

object

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

usage

dict

image_count表示生成的图片个数。

通过HTTP调用接口

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

作业提交接口

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-WorkSpace

string

指明本次调用需要使用的workspace;需要注意的是,对于子账号Apikey调用,此参数为必选项,子账号必须归属于某个workspace才能调用;对于主账号Apikey此项为可选项,添加则使用对应的workspace身份,不添加则使用主账号身份。

ws_QTggmeAxxxxx

X-DashScope-Async

string

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

enable

Body

model

string

指明需要调用的模型,可选择stable-diffusion-3.5-large或者stable-diffusion-3.5-large-turbo。

stable-diffusion-3.5-large-turbo

input.prompt

string

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

a running cat

input.init_image

string

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

http://xxx/xxx.png

parameters.size

string

生成图像的分辨率,支持长宽在5121024之间以128步长取值的任意组合,如512*1024, 1024*768等, 默认1024*1024。

1024*1024

parameters.n

integer

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

4

parameters.steps

integer

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

40

parameters.cfg

double

用于指导生成的结果与用户输入的prompt的贴合程度,越高则生成结果与用户输入的prompt更相近。目前默认4.5,倾向于输入4~5内的值。

4.5

parameters.seed

integer

图片生成时的随机种子值,如果不提供,则算法自动用一个随机生成的数字作为种子;如果指定,则根据 batch 数量分别生成 seed, seed+1, seed+2, seed+3 为参数的图片。

42

parameters.shift

double

偏移量,用于调整生成内容的某些特性或参数。默认为3.0。

3.0

出参描述

字段

类型

描述

示例值

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 3.5 模型的脚本

说明

需要使用您的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 $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "stable-diffusion-3.5-large",
    "input": {
        "prompt": "a running cat",
        "negative_prompt": "yellow cat"
    },
    "parameters": {
        "size": "512*512",
        "n":4, 
        "seed":42
    }
}'

响应示例

{
    "output": {
        "task_status": "PENDING",
        "task_id": "xxx"
    },
    "request_id": "xxx"
}

异常响应示例

在提交作业请求出错的情况下,输出的结果中会通过 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}

入参描述

字段

传参方式

类型

必选

描述

示例值

task_id

Url Path

string

需要查询作业的 task_id。

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

Authorization

Header

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 作业不存在或状态未知

output.submit_time

string

任务提交的时间戳。

2024-06-14 14:30:44.096

output.scheduled_time

string

任务计划执行的时间戳。

2024-06-14 14:30:44.112

output.end_time

string

任务执行结束的时间戳。

2024-06-14 14:31:04.197

output.results

array

执行的结果列表,列表元素为键值为URL的哈希表。

[{"url": "example_url"}]

output.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 模型的脚本。

curl -X GET \
--header "Authorization: Bearer $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":"example_url_1"
            },
            {
                "url":"example_url_2"
            }
        ],
        "task_metrics":{
            "TOTAL":2,
            "SUCCEEDED":2,
            "FAILED":0
        }
    },
    "usage":{
        "image_count":2
    }
}

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

在一次提交中,Stable Diffusion 可以根据客户的需求生成多张图片,只要其中一张图片生成成功,task_status就会被设置为SUCCEEDED状态,并且对应的作业结果会在查询的时候返回;对于失败的调用,结果中会返回失败原因。在usage计量中,只会对成功的结果计数。

{
  "request_id": "85eaba38-0185-99d7-8d16-4d9135238846",
  "output": {
    "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
    "task_status": "SUCCEEDED",
    "results": [
      {
        "url": "example_url_1"
      },
      {
        "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
  }
}

响应示例(作业失败)

如果因为某种原因作业失败,则task_status会设置为FAILED,并且通过codemessage字段指明错误原因。

{
  "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
  "output": {
    "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
    "task_status": "FAILED",
    "code": "InvalidParameter",
    "message": "The image source is invalid.",
    "task_metrics": {
      "TOTAL": 4,
      "SUCCEEDED": 0,
      "FAILED": 4
    }
  }
}

状态码说明

大模型服务平台通用状态码请查阅:错误码