快速上手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參考
前提條件
已開通服務并獲得api-key:API-KEY的獲取與配置。
已安裝SDK:安裝DashScope SDK。
圖片生成
以下示例展示了調用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用于計量的圖片個數。
狀態碼說明
DashScope通用狀態碼請查閱:返回狀態碼說明。
HTTP調用接口
功能描述
接口層面采用了異步調用的方式進行任務提交,在通過任務接口提交作業之后,系統會返回對應的作業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 | 是 | 指明需要調用的模型,目前只支持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 | 被查詢作業的作業狀態。 | 任務狀態:
|
usage.task_metrics | Object | 作業中每個batch任務的狀態(當前默認總batch數目等于1):
| "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
}
}
響應示例(作業失?。?/h3>
如果因為某種原因作業失敗,則作業狀態會設置為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
}
}
}
狀態碼說明
DashScope通用狀態碼請查閱:返回狀態碼說明。