文档

FLUX API详情

更新时间:

快速上手Flux

FLUX文生图模型

说明

支持的领域/任务:aigc

  • FLUX文生图模型目前针对开源社区的 FLUX.1 [schnell] 版本和 FLUX.1 [dev] 和一系列基于 FLUX 架构的开源社区模型进行了服务化支持, 还针对FLUX文生图模型实施了中文Prompt的适应性优化。

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

  • 用户通过输入文本指令prompt、尺寸size以及种子数seed和推理步数steps,来确定希望生成图片的样式。返回的则是用户根据文本指令生成的图片。

模型概览

模型名

模型简介

flux-schnell

FLUX.1 [schnell] 作为目前开源最先进的少步模型,不仅超越了同类竞争者,甚至还优于诸如Midjourney v6.0和DALL·E 3 (HD)等强大的非精馏模型。该模型经过专门微调,以保留预训练阶段的全部输出多样性,相较于当前市场上的最先进模型,FLUX.1 [schnell] 显著提升了在视觉质量、指令遵从、尺寸/比例变化、字体处理及输出多样性等方面的可能,为用户带来更为丰富多样的创意图像生成体验。

flux-dev

FLUX.1 [dev] 是一款面向非商业应用的开源权重、精炼模型。FLUX.1 [dev] 在保持了与FLUX专业版相近的图像质量和指令遵循能力的同时,具备更高的运行效率。相较于同尺寸的标准模型,它在资源利用上更为高效。

flux-merged

FLUX.1-merged模型结合了"DEV"在开发阶段探索的深度特性和"Schnell"所代表的高速执行优势。通过这一举措,FLUX.1-merged不仅提升了模型的性能界限,还拓宽了其应用范围。

API参考

前提条件

图片生成

以下示例展示了调用FLUX文生图模型对一个用户指令进行响应的代码。以下示例展示了调用 flux-schnell 模型API进行文生图的示例代码。如果要调用 flux-dev 模型,只需要修改 model 为 "flux-dev" 即可。

说明

需要使用您的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 = "flux-schnell"
prompt = "Eagle flying freely in the blue sky and white clouds"
prompt_cn = "一只飞翔在蓝天白云的鹰"


def sample_block_call(input_prompt):
    rsp = ImageSynthesis.call(model=model,
                              prompt=input_prompt,
                              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(input_prompt):
    rsp = ImageSynthesis.async_call(model=model,
                                    prompt=input_prompt,
                                    size='1024*1024')
    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(prompt)
    sample_async_call(prompt_cn)
// 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 = "flux-schnell";
  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)
            .size(Main.SIZE)
            .prompt(Main.PROMPT)
            .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

-

指定用于对话的FLUX文生图模型名,目前支持传入 "flux-schnell" 和 "flux-dev"

prompt

string

-

用户当前输入的期望模型生成的文本信息。用户当前输入的期望模型生成的文本信息。支持中英文,中文不超过 500 个字符,英文不超过 500 个单词,超过部分会自动截断。

size(可选)

string

1024*1024

生成图像的分辨率,目前支持"512*1024, 768*512, 768*1024, 1024*576, 576*1024, 1024*1024"六种分辨率,默认为1024*1024像素。

seed(可选)

int

-

图片生成时候的种子值,如果不提供,则算法自动用一个随机生成的数字作为种子。

steps(可选)

int

-

图片生成的推理步数,如果不提供,则默认为30。 flux-schnell 模型官方默认 steps 为4,flux-dev 模型官方默认 steps 为50。

guidance(可选)

int

3.5

指导度量值,用于在图像生成过程中调整模型的创造性与文本指导的紧密度。较高的值会使得生成的图像更忠于文本提示,但可能减少多样性;较低的值则允许更多创造性,增加图像变化。默认值为3.5。

offload(可选)

bool

False

一个布尔值,表示是否在采样过程中将部分计算密集型组件临时从GPU卸载到CPU,以减轻内存压力或提升效率。如果您的系统资源有限或希望加速采样过程,可以启用此选项,默认为False。

add_sampling_metadata(可选)

bool

True

一个布尔值,决定是否在输出的图像文件中嵌入生成时使用的提示文本等元数据信息。这对于后续跟踪或分享生成设置非常有用,默认为True。

返回结果

  • 返回结果示例

    # 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用于计量的图片个数。

HTTP调用接口

功能描述

接口层面采用了异步调用的方式进行任务提交,在通过任务接口提交作业之后,系统会返回对应的作业ID,随后客户可以通过对应的异步作业查询接口获取任务的状态并且在作业到达最终完成态后取回对应的作业结果。

前提条件

已开通服务并获得API-KEY:获取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

指明需要调用的模型,目前只支持flux-schnell。

flux-schnell

input.prompt

String

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

一只奔跑的加菲猫

parameters.size

String

生成图像的分辨率,目前支持"512*1024, 768*512, 768*1024, 1024*576, 576*1024, 1024*1024"六种分辨率,默认为1024*1024像素。

512*1024,

parameters.seed

Integer

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

42

parameters.steps

Integer

图片生成的推理步数,如果不提供,则默认为30,如果给定了,则根据 steps 数量生成图片。flux-schnell 模型官方默认 steps 为4,flux-dev 模型官方默认 steps 为50。

5

parameters.guidance

Float

指导度量值,用于在图像生成过程中调整模型的创造性与文本指导的紧密度。较高的值会使得生成的图像更忠于文本提示,但可能减少多样性;较低的值则允许更多创造性,增加图像变化。默认值为3.5。

1.7

parameters.offload

Boolean

一个布尔值,表示是否在采样过程中将部分计算密集型组件临时从GPU卸载到CPU,以减轻内存压力或提升效率。如果您的系统资源有限或希望加速采样过程,可以启用此选项,默认为False。

True

parameters.add_sampling_metadata

Boolean

一个布尔值,决定是否在输出的图像文件中嵌入生成时使用的提示文本等元数据信息。这对于后续跟踪或分享生成设置非常有用,默认为True。

False

出参描述

字段

类型

描述

示例值

output.task_id

String

本次请求的异步任务的作业id,实际作业结果需要通过异步任务查询接口获取。

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

output.task_status

String

提交异步任务后的作业状态。

PENDING

request_id

String

本次请求的系统唯一码。

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

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

说明

需要使用您的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": "flux-schnell",
    "input": {
        "prompt": "奔跑小猫"
    },
    "parameters": {
        "size": "1024*1024",
        "seed":42,
        "steps":4
    }
}'

响应示例

{
    "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任务的状态(当前默认总batch数目等于1):

  • TOTAL:总batch数目

  • SUCCEEDED:已经成功的batch数目

  • FAILED:已经失败的batch数目

"task_metrics":{

"TOTAL":1,

"SUCCEEDED":1,

"FAILED":1

}

usage.image_count

Integer

本次请求成功生成的图片数量。

1

request_id

String

本次请求的系统唯一码。

7574ee8f-38a3-4b1e-9280-11c33ab46e51

请求示例

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

说明

需要使用您的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":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

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

如果作业执行完成并成功之后,再次查询作业状态,接口将在告知作业状态的同时,一并将作业的结果返回。对于FLUX,作业在结束之后的状态会持续保留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"
            }
        ],
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    },
    "usage":{
        "image_count":2
    }
}

响应示例(作业失败)

如果因为某种原因作业失败,则作业状态会设置为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":1,
            "SUCCEEDED":0,
            "FAILED":1
        }
    }
}

错误码

如果模型调用失败并返回报错信息,请参见错误码进行解决。