aardio 文档
aardio 范例: Z-Image - AI 图像生成，Hugging Face 接口
import win.ui;
import win.ui.simpleWindow;
import fonts.fontAwesome;
import inet.http; // 必须导入，使 plus 控件支持远程图像 URL
//import gdip.webp; //导入此库 plus 控件自动支持 webp 图像
/*DSG{{*/
var winform = win.form(text="Z-Image - AI 图像生成，Hugging Face 接口";right=1150;bottom=700;bgcolor=0xF5F5F5;border="none")
winform.add(
btnCopy={cls="plus";text="复制图像 / 图像文件";left=921;top=631;right=1110;bottom=680;align="left";bgcolor=0x27AE60;border={radius=6};color=0xFFFFFF;db=1;disabled=1;dr=1;font=LOGFONT(h=-14;weight=600);iconStyle={align="left";font=LOGFONT(h=-14;name='FontAwesome');padding={left=17;top=1}};iconText='\uF0EA';notify=1;textPadding={left=37};z=20};
btnF1={cls="plus";text="AI 重写此软件";left=561;top=538;right=697;bottom=561;align="left";color=0x3498DB;db=1;dr=1;iconStyle={align="left";font=LOGFONT(h=-13;name='FontAwesome')};iconText='\uF121';notify=1;textPadding={left=18};z=25};
btnGenerate={cls="plus";text="生成图像";left=748;top=630;right=908;bottom=679;align="left";bgcolor=0x3498DB;border={radius=6};color=0xFFFFFF;db=1;dr=1;font=LOGFONT(h=-15;weight=600);iconStyle={align="left";font=LOGFONT(h=-16;name='FontAwesome');padding={left=17;top=1}};iconText='\uF1FC';notify=1;textPadding={left=37};z=19};
btnHelp={cls="plus";text="参数说明";left=867;top=341;right=987;bottom=364;align="left";color=0x3498DB;dr=1;dt=1;iconStyle={align="left";font=LOGFONT(h=-13;name='FontAwesome')};iconText='\uF059';notify=1;textPadding={left=18};z=22};
chkRandomSeed={cls="plus";text="随机种子";left=746;top=341;right=849;bottom=366;align="left";color=0x3C3C3C;dr=1;dt=1;font=LOGFONT(h=-13);iconStyle={align="left";font=LOGFONT(h=-15;name='FontAwesome');padding={left=8}};iconText='\uF096';notify=1;textPadding={left=28};z=18};
chkTranslate={cls="plus";text="英文";left=268;top=538;right=342;bottom=563;align="left";color=0x3498DB;db=1;dl=1;font=LOGFONT(h=-13);iconStyle={align="left";font=LOGFONT(h=-15;name='FontAwesome');padding={left=8}};iconText='\uF204';notify=1;textPadding={left=28};z=24};
comboResolution={cls="combobox";left=745;top=120;right=1105;bottom=145;dr=1;dt=1;edge=1;items={"1024x1024 ( 1:1 )","864x1152 ( 3:4 )","1152x864 ( 4:3 )","1248x832 ( 3:2 )","832x1248 ( 2:3 )","1152x896 ( 9:7 )","896x1152 ( 7:9 )","1280x720 ( 16:9 )","720x1280 ( 9:16 )","1344x576 ( 21:9 )","576x1344 ( 9:21 )","1280x1280 ( 1:1 )","1104x1472 ( 3:4 )","1472x1104 ( 4:3 )","1536x1024 ( 3:2 )","1024x1536 ( 2:3 )","1440x1120 ( 9:7 )","1120x1440 ( 7:9 )","1536x864 ( 16:9 )","864x1536 ( 9:16 )","1680x720 ( 21:9 )","720x1680 ( 9:21 )","1536x1536 ( 1:1 )","1296x1728 ( 3:4 )","1728x1296 ( 4:3 )","1872x1248 ( 3:2 )","1248x1872 ( 2:3 )","1728x1344 ( 9:7 )","1344x1728 ( 7:9 )","2048x1152 ( 16:9 )","1152x2048 ( 9:16 )","2016x864 ( 21:9 )","864x2016 ( 9:21 )"};mode="dropdownlist";z=11};
editPrompt={cls="edit";left=30;top=565;right=710;bottom=680;autohscroll=false;bgcolor=0xFFFFFF;db=1;dl=1;dr=1;edge=1;multiline=1;vscroll=1;z=8};
editSeed={cls="edit";text="42";left=745;top=304;right=1105;bottom=329;dr=1;dt=1;edge=1;z=13};
editStep={cls="edit";text="8";left=745;top=181;right=1105;bottom=206;dr=1;dt=1;edge=1;z=15};
editTimeShift={cls="edit";text="3.0";left=745;top=243;right=1105;bottom=268;dr=1;dt=1;edge=1;z=17};
labelResolution={cls="bkplus";text="分辨率 (Resolution)：";left=745;top=95;right=900;bottom=115;align="left";color=0x666666;dr=1;dt=1;z=10};
labelSeed={cls="bkplus";text="种子 (Seed)：";left=745;top=280;right=900;bottom=300;align="left";color=0x666666;dr=1;dt=1;z=12};
labelSettings={cls="bkplus";text="生成设置";left=745;top=65;right=900;bottom=85;align="left";color=0x999999;dr=1;dt=1;font=LOGFONT(h=-13;weight=600);z=9};
labelTimeShif={cls="bkplus";text="时间偏移 (Time Shift)：";left=745;top=218;right=900;bottom=238;align="left";color=0x666666;dr=1;dt=1;z=16};
labelTip={cls="plus";left=767;top=546;right=1069;bottom=597;border={color=0xFF008000;radius=16;width=1};db=1;dr=1;hide=1;z=23};
optimizeLink={cls="plus";text="优化提示词";left=167;top=538;right=269;bottom=561;align="left";color=0x3498DB;db=1;dl=1;iconStyle={align="left";font=LOGFONT(h=-13;name='FontAwesome')};iconText='\uF0D0 ';notify=1;textPadding={left=18};z=21};
picturebox={cls="plus";text="请在下方输入提示词生成图像";left=30;top=57;right=710;bottom=500;border={color=0xFFEEEEEE;radius=8;width=1};color=0x999999;db=1;dl=1;dr=1;dt=1;font=LOGFONT(h=-16);iconStyle={font=LOGFONT(h=-60;name='FontAwesome')};iconText='\uF03E';notify=1;repeat="scale";textPadding={top=100};z=3};
progressBar={cls="plus";left=812;top=382;right=1023;bottom=593;bgcolor=0xECF0F1;border={radius=3};db=1;dr=1;forecolor=0x3498DB;hide=1;z=6};
promptLabel={cls="bkplus";text="提示词 (Prompt)：";left=30;top=540;right=200;bottom=560;align="left";color=0x999999;db=1;dl=1;font=LOGFONT(h=-13;weight=600);z=7};
settingsGroup={cls="bkplus";left=730;top=57;right=1120;bottom=612;bgcolor=0xFFFFFF;border=1;db=1;dr=1;dt=1;z=1};
stepsLabel={cls="bkplus";text="步数 (Steps)：";left=745;top=157;right=900;bottom=177;align="left";color=0x666666;dr=1;dt=1;z=14};
titleBar={cls="bkplus";left=0;top=0;right=1150;bottom=46;bgcolor=0x2C3E50;dl=1;dr=1;dt=1;z=2};
titleIcon={cls="bkplus";text='\uF03E';left=326;top=6;right=366;bottom=42;color=0x3498DB;dl=1;dt=1;font=LOGFONT(h=-20;name='FontAwesome');z=5};
titleText={cls="bkplus";text="造相（Z-Image Turbo）文生图 HF 接口";left=16;top=10;right=332;bottom=34;color=0xFFFFFF;dl=1;dt=1;font=LOGFONT(h=-16;weight=700);z=4}
)
/*}}*/
// UI 初始化设置
winform.editPrompt.setPadding(5,5,5,5); // 提示词输入框内边距
winform.editPrompt.text = `A cute 3D rendered cat, wearing sunglasses, cyberpunk style, neon lights.`; // 默认提示词
// 分辨率下拉框默认选中项
winform.comboResolution.selText = "1024x1024 ( 1:1 )";
// 生成按钮点击事件
winform.btnGenerate.oncommand = function(){
var prompt = winform.editPrompt.text;
if(!#string.trim(prompt)) {
return winform.msgbox("请输入提示词", "提示", "warn");
}
winform.btnCopy.text = "复制图像 / 图像文件";
winform.btnCopy.iconText = '\uF0EA'
winform.btnCopy.disabled = true; // 生成期间禁止下载
winform.picturebox.imageCreateTime = time();
// 从 UI 控件获取生成参数
var resolution = winform.comboResolution.selText;
var seed = tonumber(winform.editSeed.text) || 42;
var steps = tonumber(winform.editStep.text) || 8;
var timeShift = tonumber(winform.editTimeShift.text) || 3.0;
var randomSeed = winform.chkRandomSeed.checked;
// 更新 UI 状态：禁用按钮，显示加载动画
winform.btnGenerate.disabledText = {'\uF254';'\uF251';'\uF252';'\uF253';'\uF250'}; // 沙漏动画
// 初始化图片框和进度条
winform.picturebox.background = null;
winform.picturebox.iconText = '\uF03E'; // 默认图片图标
winform.picturebox.text = "正在连接 AI 模型...";
// 设置进度条为无限循环模式 (Gradio 具体的进度难以精确获取)
winform.progressBar.startProgress();
// 开启线程调用 Gradio API
thread.invoke(
function(winform, prompt, resolution, seed, steps, timeShift, randomSeed){
import web.rest.gradioClient;
// 创建 Gradio 客户端，参数 1 指定 Hugging Face Space ID
var gradio = web.rest.gradioClient("Tongyi-MAI/Z-Image-Turbo",{
// proxy = "socks=127.0.0.1:1081",// 可选指定代理服务器
// token = "hf_********" // 可选指定 token 以提高配额
});
winform.picturebox.text = "正在生成图像 (需排队)...";
// 调用 Gradio API，参数顺序必须严格对应 API 定义
// [prompt, resolution, seed, steps, shift, random_seed, gallery_images]
var result, err = gradio.xcall.generate({
data = [
prompt, // 提示词
resolution, // 分辨率
seed, // 种子
steps, // 步数
timeShift, // 时间偏移
randomSeed, // 开启随机种子
[] // Gallery (传空数组)
]
});
//不同 Space 的 API 接口与参数定义略有不同，
// 可用下面的方法打印接口可用端点发给 AI 修改
//console.dumpJson( gradio.getInfo() )
// 处理返回结果
var imageInfo = result[[1]][[1]];//直接下标用于 null 值不会报错
if( imageInfo ){
var imageUrl = imageInfo.image.url;
var seedUsed = result[2]; // Gradio API 返回的实际种子
if(imageUrl){
// 设置 plus 控件背景图，界面线程会自动导入 inet.http 支持自动下载远程图片
winform.picturebox.background = imageUrl;
// 清除文字和图标
winform.picturebox.text = null;
winform.picturebox.iconText = null;
// 启用下载按钮
winform.btnCopy.disabled = false;
// 在标题栏提示成功
winform.text = "造相 Z-Image - 生成成功 (Seed: " + seedUsed + ")";
// 如果是随机种子，更新 UI 上的种子输入框为实际使用的种子
if(randomSeed) winform.editSeed.text = tostring(seedUsed);
winform.showTip('已生成图像，双击图像放大。');
}
} else {
winform.msgboxErr(err || "生成图像失败，请检查网络连接或提示词是否符合要求。");
winform.picturebox.text = "生成失败";
winform.picturebox.iconText = '\uF057'; // 错误图标 (FontAwesome circle-xmark)
}
// 恢复 UI 状态
winform.btnGenerate.disabledText = null; // 停止沙漏动画
winform.progressBar.stopProgress(); // 停止进度条
winform.progressBar.hide = true; // 隐藏进度条
}, winform, prompt, resolution, seed, steps, timeShift, randomSeed // 将 UI 控件值作为参数传入线程
);
};
// 下载按钮点击事件
var tempImageDir = io.tmpname();
io.createDir(tempImageDir)
winform.onDestroy = function(){
import fsys;
fsys.delete(tempImageDir);
}
winform.btnCopy.oncommand = function(){
if(winform.picturebox.background){
var filename = (winform.picturebox.imageCreateTime||time()).format("%Y%m%d_%H%M%S.png")
var imagePath = io.joinpath(tempImageDir,filename);
winform.picturebox.background.save(imagePath);
if(winform.btnCopy.text == "打开图像文件"){
raw.explore(imagePath);
winform.showTip('已打开图像');
winform.btnCopy.text = "复制图像 / 图像文件";
winform.btnCopy.iconText = '\uF0EA'
}
else{
import win.clip.bitmap;
win.clip.bitmap.writeHtml(winform.picturebox.background);
import win.clip.file;
win.clip.file.write(imagePath,"move",false);
winform.btnCopy.text = "打开图像文件";
winform.btnCopy.iconText = '\uF1C5';
winform.showTip('已复制图像与图像文件');
}
}
else {
winform.showTip('请先生成图像。');
}
};
winform.showTip = function(str){
winform.labelTip.text = str;
winform.labelTip.show(true);
winform.setTimeout(
function(){
winform.labelTip.show(false);
},5000
)
}
// 应用简单无边框窗口样式（最大化、最小化、关闭按钮等）
win.ui.simpleWindow(winform);
winform.progressBar.setPieRange(0,100);
winform.btnHelp.onMouseClick = function(){
import web.form.simpleMarkdown;
var frmHelp = win.form(text="Z-Image 参数说明";right=580;bottom=644;parent=winform)
var wb = web.form.simpleMarkdown(frmHelp);
var md = /***
简单来说，AI 生成图像的过程，可以想象成一个画家从一团随机的“数字噪音”（像电视没信号时的雪花点）开始，一步步地根据你的“提示词”把它修改成一幅清晰、具体的画。
这几个参数就是用来控制这个“绘画”过程的。
---
### 1. 步数 (Steps)
* **是什么？**
“步数”指的是 AI 从一团噪音中“提炼”出最终图像所经历的**迭代或优化的次数**。每一步，AI 都会根据你的提示词，对图像进行一次去噪和修正，让它离最终目标更近一点。
* **它如何影响图像？**
* **步数太少**：就像画家只画了个草稿。图像可能会模糊、细节缺失、出现奇怪的伪影，或者看起来“没画完”。
* **步数适中**：图像会变得清晰、细节丰富、内容完整。这是质量和速度的平衡点。
* **步数太多**：在达到一定质量后，再增加步数对画质的提升会变得微乎其微（收益递减），但生成时间会显著增加。有时过多的步数甚至可能导致细节“过曝”或不自然。
* **实用建议**
对于像 Z-Image-Turbo 这样的**“加速”模型**，它被特别设计为可以用**非常少**的步数（例如 4-8 步）就能生成高质量的图像。这是它的核心优势。对于其他常规模型，通常需要 20-30 步。所以，在这个软件里，**保持默认的 8 步通常是最佳选择**。
---
### 2. 种子 (Seed)
* **是什么？**
“种子”是一个数字，它决定了 AI 开始绘画前那团**初始“数字噪音”的具体模式**。你可以把它理解为一副扑克牌的“初始排列顺序”。
* **它如何影响图像？**
* **相同的种子 + 相同的提示词 + 相同的设置 = 100% 相同的图像**。
* **不同的种子**，即使其他一切都相同，也会生成一张**构图、角色、姿势等完全不同**的全新图像。
* **实用建议**
* **探索创意时**：勾选“随机种子”（Random Seed），让 AI 每次都给你不同的结果，就像开盲盒一样充满惊喜。
* **优化作品时**：当你生成了一张很喜欢的图，但想微调一下细节（比如把“红色的车”改成“蓝色的车”），就**取消勾选“随机种子”，并使用生成那张图时返回的种子号**。这样，AI 会在保持整体构图和风格不变的情况下，只修改你指定的细节。这是非常强大的功能！
---
### 3. 时间偏移 (Time Shift)
* **是什么？**
这是一个相对更技术的参数，与扩散模型内部的“时间步（timestep）”调度有关。你可以把它想象成一个**精细的调节旋钮**，它影响 AI 在“绘画”的不同阶段（从早期勾勒轮廓到晚期添加细节）如何分配它的“注意力”。
* **它如何影响图像？**
这个参数主要是由模型开发者为了在**极低的步数下**达到最佳效果而调整出来的。对于 Z-Image-Turbo 模型，开发者发现将这个值设置在 `3.0` 左右时，可以在很少的步数内（如 4-8 步）最好地平衡图像的细节和整体结构。偏离这个值可能会导致在低步数下效果变差。
* **实用建议**
对于普通用户来说，**这个参数最好保持默认值 `3.0` 不变**。它不像“步数”和“种子”那样需要经常调整。你可以把它看作是这个模型的“最佳出厂设置”之一。
### 总结
| 参数 | 通俗比喻 | 作用 | 建议 |
| :--- | :--- | :--- | :--- |
| **步数 (Steps)** | 画家绘画的精细度 | 控制图像质量和生成时间 | 使用模型推荐值（如 8） |
| **种子 (Seed)** | 牌局的初始发牌顺序 | 控制图像的随机性和可复现性 | 探索时用“随机”，优化时用“固定” |
| **时间偏移 (Time Shift)** | 引擎的最佳点火时机 | 微调模型在生成过程中的内部行为 | **保持默认值**，无需修改 |
***/
wb.doScript(`window.onWriteEnd = function(){}` )
wb.write(md);
frmHelp.show(3/*_SW_SHOWMAXIMIZED*/);
}
winform.optimizeLink.oncommand = function(id,event){
var prompt = string.trim(winform.editPrompt.text);
if(!#prompt) {
return winform.editPrompt.showWarningTip("请先输入提示词");
}
winform.btnGenerate.disabled = true;
winform.chkTranslate.disabled = true;
winform.btnCopy.disabled = true;
winform.optimizeLink.disabledText = ['\uF254','\uF251','\uF252','\uF253','\uF250']
thread.invoke(
function(winform,prompt){
import web.rest.aiChat;
var aiClient = web.rest.aiChat(
key = '\0\1\96';
url = "https://ai.aardio.com/api/v1/";//接口地址
model = "prompt";
temperature = 0.5;//温度
maxTokens = 1024 //最大回复长度
)
//2. 第二步：创建消息队列，必须在这里保存对话，不然 AI 的回复没有上下文。
//---------------------------------------------------------------------
var msg = web.rest.aiChat.message();
//可调用 msg.system() 函数添加系统提示词。
msg.system(`# 角色
你是一位顶级的 AI 绘画提示词（Prompt）优化师。
# 任务
你的核心任务是分析、重构并优化用户输入的初步提示词，旨在显著提升生成图像的艺术感、细节丰富度和整体质量。
# 工作流程
1. **保持核心意图**：精确理解并保留用户提示词的原始核心创意。
2. **丰富关键细节**：围绕核心创意，从以下至少三个维度进行扩展和具象化：
* **主体细节**：为核心主体增添更具体的特征、服装、表情或动作。
* **环境与背景**：构建一个生动、有故事感的背景环境。
* **光照与氛围**：设定明确的光线（如“清晨柔和的光”、“霓虹灯闪烁的夜晚”）和整体氛围（如“神秘”、“宁静”、“赛博朋克”）。
* **构图与视角**：指定一个有趣的视角（如“特写”、“广角”、“从下往上”）。
* **艺术风格**：定义一种清晰的艺术风格（如“照片级真实感”、“吉卜力动画风格”、“水彩画”）。
3. **提升画质词缀**：添加行业通用的高画质描述词，如 "best quality", "masterpiece", "ultra-detailed"。
# 要求
* 无需解释你的思考过程。
* 请始终用` +(winform.chkTranslate.checked?"英文":"中文")+ `输出回复
# 背景
- 用户当前选择的大模型是 Z-Image-Turbo 。
- 用户当前选择图像分辨率为：`+winform.comboResolution.selText)
//添加用户提示词
msg.prompt( "请优化: " + prompt );
winform.editPrompt.text = "";
var resp,err = aiClient.messages(msg,
function(deltaText,reasoning){
if(deltaText) winform.editPrompt.appendText(deltaText);
}
);
winform.btnGenerate.disabled = false;
winform.btnCopy.disabled = false;
winform.chkTranslate.disabled = false;
winform.optimizeLink.disabledText = null;
},winform,prompt
)
}
winform.picturebox.onMouseDoubleClick = function(wParam,lParam){
if(!winform.picturebox.background){
return winform.msgboxErr("请先生成图像。", "错误");
}
var frmPreview = win.form(text="aardio form";right=757;bottom=466;bgcolor=0xFFFFFF;border="none")
frmPreview.add(
btnClose={cls="close";text="×";left=725;top=3;right=753;bottom=31;bgcolor=0xCC8B94;dr=1;dt=1;font=LOGFONT(h=-21);notify=1;z=2};
picturebox={cls="plus";left=0;top=0;right=758;bottom=467;bgcolor=0xFFFFFF;db=1;dl=1;dr=1;dt=1;foreRepeat="scale";notify=1;repeat="scale";z=1}
)
frmPreview.onActivateApp = function(activated){ if(!activated)frmPreview.close() }
frmPreview.onCancel = function(){ frmPreview.close() }
frmPreview.picturebox.onMouseDoubleClick = function(){ frmPreview.close() }
frmPreview.picturebox.foreground = winform.picturebox.background;
frmPreview.fullscreen()
frmPreview.btnClose.oncommand = function(id,event){
frmPreview.close();
}
frmPreview.btnClose.show(true);
}
// 随机种子复选框样式及默认状态
winform.chkRandomSeed.skin({
color={
default=0xFF3C3C3C;
hover=0xFF0078D4;
active=0xFF005A9E;
disabled=0xFFAAAAAA;
};
checked={ // 选中状态的样式
iconText='\uF046' // Checkmark icon (FontAwesome solid square check)
}
});
winform.chkRandomSeed.checked = true; // 默认开启随机种子
// 生成按钮皮肤设置
winform.btnGenerate.skin({
background={
default=0xFF3498DB; // 蓝色
hover=0xFF2980B9;
active=0xFF1F618D;
disabled=0xFFBDC3C7 // 禁用状态灰色
};
color={
default=0xFFFFFFFF; // 白色文字
disabled=0xFF7F8C8D // 禁用状态深灰色文字
}
});
winform.btnCopy.skin({
background={
default=0xFF27AE60; // 绿色
hover=0xFF229954;
active=0xFF1E8449;
disabled=0xFFBDC3C7 // 禁用状态灰色
};
color={
default=0xFFFFFFFF; // 白色文字
disabled=0xFF7F8C8D // 禁用状态深灰色文字
}
});
winform.btnF1.skin({
color = {
default = 0xFF3498DB;
hover = 0xFF2980B9;
active = 0xFF1F618D;
disabled=0xFFAAAAAA;
}
})
winform.optimizeLink.skin({
color = {
default = 0xFF3498DB;
hover = 0xFF2980B9;
active = 0xFF1F618D;
disabled=0xFFAAAAAA;
}
})
winform.btnHelp.skin({
color = {
default = 0xFF3498DB;
hover = 0xFF2980B9;
active = 0xFF1F618D;
}
})
winform.chkTranslate.skin({
color={
default=0xFF3498DB;
hover=0xFF0078D4;
active=0xFF005A9E;
disabled=0xFFAAAAAA;
};
checked={ // 选中状态的样式
iconText='\uF205';
color={
default=0xFF3498DB;
hover=0xFF0078D4;
active=0xFF005A9E;
disabled=0xFFAAAAAA;
};
}
});
winform.btnF1.oncommand = function(id,event){
winform.show(6/*_SW_MINIMIZE*/);
import ide;
ide.openCode("//调用 Z-Image-Turbo 生图")
thread.delay(200);
var codeEditor = ide.getActiveCodeEditor();
codeEditor.setFocus();
thread.delay(500);
import winex;
var caret = winex.getCaret(codeEditor.hwnd)
if(!caret){
caret = codeEditor.getRect(true);
caret.height = winform.dpiScale(16);
}
import winex.tooltip;
winex.tooltip.balloon("请按 F1 键，AI 助手将自动续写代码",caret.left,caret.bottom,4000);
}
winform.chkTranslate.checked = true;
winform.show();
win.loopMessage();
Markdown 格式