在鸿蒙（HarmonyOS）生态中，文生图（Text-to-Image）能力的集成主要分为云端 API 调用和端侧 AI 推理两条技术路径。开发者可根据业务场景的实时性、隐私要求及算力条件，灵活选择或组合使用。

一、 核心架构与技术路径

1. 云端 API 集成
   通过 HTTP 请求调用第三方大模型服务（如火山引擎、Ark API 等）。这是目前最主流的方式，能够生成高质量、高分辨率的图像。核心流程包括：Prompt 工程优化、HTTP 请求封装、SSE 流式响应解析（部分服务支持）以及结果缓存。

2. 端侧 AI 推理
   利用鸿蒙的 Core Vision Kit 和 NPU 硬件加速，在设备本地完成图像生成或增强。典型应用包括图像超分（将低清小图秒变原生高清）、文搜图（通过自然语言搜索本地图片）以及图片风格迁移。这种方式完全离线，隐私安全且无网络延迟。

3. 系统级 AI 增强
   鸿蒙系统图库已内置 AI 修图能力，如 AI 沾色（一键生成剪影、增强光影）和 魔法移图（智能贴纸合成、3D 空间位移），开发者可通过系统接口或参考其设计思路，为应用注入原生级的创意体验。

二、 核心开发能力与集成机制

1. Prompt 工程与增强
   直接传递用户原始输入往往效果不佳。需设计 enrichPrompt 方法，自动追加风格描述符（如“儿童绘本动画风格”、“赛博朋克”）和生成参数（如 --watermark true），将模糊意图转化为模型可理解的高质量 Prompt。

2. 健壮的 HTTP Service 封装
   图片生成是计算密集型任务，必须对网络请求进行深度封装：

   • 超时配置：readTimeout 需设置为 90 秒以上，远超普通 API。
   • 连接管理：使用 try/finally 确保 request.destroy() 执行，防止连接泄漏。
   • 状态隔离：通过 requestId 或状态版本号，确保连续点击时，只有最后一次请求的结果能更新 UI。

3. 端侧能力调用

   • 图像超分：通过 ImageSRAnalyzer API，输入原图即可获得 4 倍放大的高清 PixelMap，首次调用需联网下载模型，后续完全离线。
   • 文搜图：使用 textSearchImage API，将图片插入索引库后，即可通过自然语言（如“蓝色恐龙”）进行毫秒级语义搜索。

三、 性能优化

1. 失败场景的优雅降级
   AI 生图失败时，切勿立即清空预览区。应保留上一次成功的图片，并根据错误类型（限流、鉴权失败、超时）给出差异化提示（“稍后再试”、“修改描述”），而非笼统的“生成失败”。

2. 密钥安全与合规
   严禁将 API Key 硬编码在 ArkTS 页面中。应通过后端代理、受控配置或用户安全输入的方式获取凭据，并在错误日志中过滤敏感字段。

3. 端侧能力限制
   Core Vision Kit 的图像超分、文搜图等功能不支持模拟器，必须使用真机调试。首次调用需联网，且同一进程内不支持对同一分析器的并发调用。

4. 流式响应解析
   若接入支持 SSE 的文生图或 Prompt 增强服务，必须正确处理 data: [DONE] 终止标记，否则 JSON 解析会抛出异常，导致整个流式任务中断。

四、 应用实战：Prompt 工程与 HTTP Service 健壮封装

在鸿蒙 ArkTS 开发中，文生图的核心在于将用户的模糊意图转化为模型可理解的高质量 Prompt，并通过健壮的 HTTP 服务处理计算密集型的生成任务。

1. Prompt 增强策略
   设计 enrichPrompt 方法，实现三层增强：空输入兜底（默认风格）、追加风格描述符（如“儿童绘本动画风格”）以及生成参数控制（如 --watermark true）。这确保了无论用户输入何种内容，模型都能输出符合产品定位的图像。
2. HTTP 请求深度封装
   图片生成耗时较长，必须将 readTimeout 设置为 90 秒以上。同时，使用 try/finally 模式确保 request.destroy() 始终执行，防止连接泄漏。
3. 连续点击防抖与状态隔离
   通过 requestId 或状态版本号机制，确保在用户连续点击生成时，只有最后一次请求的结果有资格更新 UI，避免旧请求覆盖新结果。

// ImageGenerationService.ets
import { http } from '@kit.NetworkKit';

export class ImageGenerationService {
    // 1. Prompt 三层增强策略：兜底、风格注入、参数控制
    static enrichPrompt(raw: string): string {
        const trimmed = raw.trim();
        if (trimmed === '') {
            return '儿童蜡笔画风格，明亮温暖，一个可爱的角色在轻快地探索奇妙世界';
        }
        return trimmed + '，儿童绘本动画风格，保留手绘线条和明亮色彩，动作温和可爱 --duration 5 --camerafixed false --watermark true';
    }

    // 2. 健壮的 HTTP 请求封装（含超时配置、连接管理与状态隔离）
    static async requestImage(apiKey: string, prompt: string, requestId: number): Promise<string> {
        const request = http.createHttp();
        try {
            const response = await request.request('https://your-api-endpoint/images/generations', {
                method: http.RequestMethod.POST,
                connectTimeout: 30000,
                readTimeout: 90000, // 核心：图片生成耗时，readTimeout 设为 90 秒
                header: { 
                    'Content-Type': 'application/json',
                    'Authorization': `Bearer ${apiKey}` 
                },
                extraData: JSON.stringify({ prompt: ImageGenerationService.enrichPrompt(prompt) })
            });
            // 解析响应并返回图片 URL
            const data = JSON.parse(response.result as string);
            return data.data[0].url || '';
        } catch (err) {
            throw new Error('图片生成请求失败');
        } finally {
            request.destroy(); // 核心：确保无论成功失败都销毁连接，防止泄漏
        }
    }
}

// 页面层状态隔离防抖示例
@Entry
@Component
struct ImageGenPage {
    @State imageUrl: string = '';
    private currentRequestId: number = 0;

    async generateImage(prompt: string) {
        const requestId = ++this.currentRequestId; // 递增版本号
        try {
            const url = await ImageGenerationService.requestImage('your-key', prompt, requestId);
            // 核心：只有当返回的 requestId 等于当前最新的 requestId 时，才更新 UI
            if (requestId === this.currentRequestId) {
                this.imageUrl = url;
            }
        } catch (e) {
            // 失败时保留上一次成功的 imageUrl，不执行 this.imageUrl = ''
        }
    }
}

五、 进阶场景：端侧图像超分与语义搜图

除了云端生成，鸿蒙系统级 AI 提供了强大的端侧图像处理能力，完全离线且隐私安全。

1. 图像超分（Image SR）
   利用 Core Vision Kit 的 ImageSRAnalyzer，可将低分辨率图片秒级放大 4 倍。首次调用需联网下载轻量级模型，后续推理完全在设备 NPU 上离线完成，适合相册增强、老旧照片修复等场景。
2. 自然语言搜图（Text-to-Image Search）
   通过 textSearchImage API，将本地图片插入语义索引库后，用户即可使用自然语言（如“海边的日落”、“穿红裙子的女孩”）进行毫秒级精准搜索，彻底改变传统标签搜索的体验。

// LocalVisionKitDemo.ets
import { visionCore } from '@kit.CoreVisionKit'; // 假设的 Vision Kit 命名空间

export class LocalVisionKitDemo {
    // 1. 端侧图像超分（4倍放大）
    public static async superResolution(inputPixelMap: PixelMap): Promise<PixelMap> {
        try {
            const analyzer = new visionCore.ImageSRAnalyzer();
            // 核心：首次调用需联网下载模型，后续离线运行
            const result = await analyzer.process(inputPixelMap); 
            return result.pixelMap;
        } catch (err) {
            console.error('端侧图像超分失败:', err);
            return inputPixelMap;
        }
    }

    // 2. 自然语言文搜图
    public static async textSearchImage(query: string): Promise<Array<string>> {
        try {
            // 核心：通过自然语言进行毫秒级语义搜索
            const results = await visionCore.textSearchImage(query);
            return results.map(item => item.imageUri);
        } catch (err) {
            console.error('文搜图失败:', err);
            return [];
        }
    }
}

在实际落地文生图与端侧 AI 能力时，需特别注意以下工程规范：

1. 失败场景的优雅降级
   AI 生图失败时，严禁立即清空预览区。应保留上一次成功的图片，并根据错误码给出差异化提示（如限流提示“稍后再试”、输入错误提示“修改描述”），保障创作体验的连续性。
2. 密钥安全与合规声明
   严禁将第三方 API Key 硬编码在 ArkTS 页面中。应通过后端代理或受控配置获取凭据。同时，应用上架时需明确进行 AI 生成合成服务的合规性声明。
3. 端侧真机调试与并发限制
   Core Vision Kit 的图像超分、文搜图等功能不支持模拟器，必须使用真机调试。此外，同一进程内不支持对同一分析器的并发调用，需做好任务队列管理。
4. SSE 流式响应解析
   若接入支持 SSE 的 Prompt 增强或生图服务，必须正确处理 data: [DONE] 终止标记，否则 JSON 解析会抛出异常，导致整个流式任务中断。

// AiSafetyAndStream.ets

export class AiSafetyAndStream {
    // 1. 失败场景的优雅降级策略
    public static handleError(errorCode: string, lastSuccessUrl: string): { url: string, tip: string } {
        switch (errorCode) {
            case 'rateLimited':
                return { url: lastSuccessUrl, tip: '当前使用人数过多，请稍后再试' };
            case 'unauthorized':
                return { url: lastSuccessUrl, tip: '服务授权已过期，请检查配置' };
            case 'emptyPrompt':
                return { url: lastSuccessUrl, tip: '请输入描述后再试' };
            default:
                return { url: lastSuccessUrl, tip: '生成遇到问题，已为您保留上次作品' };
        }
    }

    // 2. SSE 流式响应解析（正确处理终止标记）
    public static parseSSEStream(rawText: string): string {
        const lines = rawText.split('\n');
        let result = '';
        for (const line of lines) {
            if (line.startsWith('data: ')) {
                const data = line.substring(6).trim();
                // 核心：正确处理终止标记，防止 JSON 解析异常
                if (data === '[DONE]') break; 
                try {
                    const parsed = JSON.parse(data);
                    result += parsed.content || '';
                } catch (e) {
                    // 忽略解析失败的片段
                }
            }
        }
        return result;
    }
}