Cangejie Magic智谱AI文生图API实战详解
目录
引言
质谱AI文生图API
接口请求
请求参数
响应参数
Cangjie Magic相关代码的修改
src/model/model_manager.cj文件修改
增加ZhipuAIImageModel
程序测试
结束语
引言
当创意遇上代码，AI文生图技术正在重塑视觉创作边界！质谱AI的CogView模型以其对文本描述的精准理解和多样化风格表达能力，为开发者提供了强大的图像生成工具。本文将深入解析如何通过质谱AI文生图API实现创意可视化，并重点解决开发者在华为Cangjie Magic框架中集成该API时遇到的关键兼容性问题——从接口参数详解到框架源码改造，手把手带您打通技术集成全链路。
质谱AI文生图API
质谱AI的CogView模型适用于图像生成任务，通过对用户文字描述快速、精准的理解，让AI的图像表达更加精确和个性化，其API接口参见智谱AI开放平台。
接口请求
| 传输方式 | HTTPS |
|---|---|
| 请求地址 | https://open.bigmodel.cn/api/paas/v4/images/generations |
| 调用方式 | 同步调用，等待模型执行完成并返回最终结果 |
| 字符编码 | UTF-8 |
| 接口请求格式 | JSON |
| 响应格式 | JSON |
| 接口请求类型 | POST |
| 开发语言 | 任意可发起 http 请求的开发语言 |
请求参数
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| model | String | 是 | 模型编码，目前支持：cogview-4-250304、cogview-4、cogview-3-flash |
| prompt | String | 是 | 所需图像的文本描述 |
| quality | String | 否 | 生成图像的质量，默认为 standard hd : 生成更精细、细节更丰富的图像，整体一致性更高，耗时约20 秒 standard :快速生成图像，适合对生成速度有较高要求的场景，耗时约 5-10 秒 此参数仅支持 cogview-4-250304 。 |
| size | String | 否 | 图片尺寸，推荐枚举值：1024x1024,768x1344,864x1152,1344x768,1152x864,1440x720,720x1440，默认是1024x1024。 自定义参数：长宽均需满足 512px - 2048px 之间，需被16整除, 并保证最大像素数不超过 2^21 px。 |
| user_id | String | 否 | 终端用户的唯一ID，协助平台对终端用户的违规行为、生成违法及不良信息或其他滥用行为进行干预。ID长度要求：最少6个字符，最多128个字符。 |
响应参数
| 参数名称 | 类型 | 参数说明 |
|---|---|---|
| created | String | 请求创建时间，是以秒为单位的Unix时间戳。 |
| data | List | 数组，包含生成的图片 URL。目前数组中只包含一张图片。 |
| url | String | 图片链接。图片的临时链接有效期为 30天，请及时转存图片。 |
| content_filter | List | 返回内容安全的相关信息。 |
| role | String | 安全生效环节，包括 role = assistant 模型推理，role = user 用户输入，role = history 历史上下文 |
| level | Integer | 严重程度 level 0-3，level 0表示最严重，3表示轻微 |
Cangjie Magic相关代码的修改
质谱AI的接口和OpenAI差不多，但是如果直接在Cangjie Magic中用OpenAi接口调用，会产生如下错误：
An exception has occurred:
Exception: Convert to String error. Value: 1749968827at magic.jsonable.JsonableException::init(std.core::String)(/home/developer/.cjpm/git/magic/ca8cba8d704c88285e5a53cffdd8f03092a06e37/src/jsonable/jsonable.cj:38)at magic.jsonable.lambda.33()(/home/developer/.cjpm/git/magic/ca8cba8d704c88285e5a53cffdd8f03092a06e37/src/jsonable/jsonable.cj:49)at magic.jsonable.String::fromJsonValue(encoding.json::JsonValue)(/home/developer/.cjpm/git/magic/ca8cba8d704c88285e5a53cffdd8f03092a06e37/src/jsonable/jsonable.cj:48)at magic.model.openai.OpenAIImageResponse::fromJsonValue(encoding.json::JsonValue)(/home/developer/.cjpm/git/magic/ca8cba8d704c88285e5a53cffdd8f03092a06e37/src/model/openai/image.cj:18)at magic.model.openai.OpenAIImageModel::create(magic.core.model::ImageRequest)(/home/developer/.cjpm/git/magic/ca8cba8d704c88285e5a53cffdd8f03092a06e37/src/model/openai/image.cj:64)at genimg.main()(/home/developer/IDEProjects/genimg/src/main.cj:54)
产生这个错误的原因是质谱AI返回的数据中的created格式和OpenAI的略有不同，所以Cangjie Magic在处理Json数据时发生了错误。为此需要单独写个质谱AI的接口。
src/model/model_manager.cj文件修改
先增加：
import magic.model.zhipuai.ZhipuAIImageModel修改createImageModel函数：
public static func createImageModel(modelConfig: ModelConfig): ImageModel {match (modelConfig.service) {case "openai" =>return OpenAIImageModel(modelConfig.name, apiKey: modelConfig.apiKey, baseURL: modelConfig.baseURL)case "siliconflow" =>return SiliconflowImageModel(modelConfig.name, apiKey: modelConfig.apiKey, baseURL: modelConfig.baseURL)case "zhipuai" =>return ZhipuAIImageModel(modelConfig.name, apiKey: modelConfig.apiKey, baseURL: modelConfig.baseURL)case _ =>throw UnsupportedException("Unreachable")}}增加ZhipuAIImageModel
创建src/model/zhipuai/image.cj文件如下：
/** Copyright (c) Huawei Technologies Co., Ltd. 2024-2025. All rights reserved.*/
package magic.model.zhipuaiimport magic.core.model.*
import magic.utils.http.*
import magic.dsl.jsonable
import magic.jsonable.*import encoding.json.*
import std.collection.{HashMap, ArrayList}@jsonable
private class ZhipuAIImageResponse {let created: Int64let data: Array<ZhipuAIImageData>
}@jsonable
private class ZhipuAIImageData {let url: String
}public class ZhipuAIImageModel <: ImageModel {private let model: Stringprivate let baseURL: Stringpublic let apiKey: Stringpublic init(model: String,apiKey!: String,baseURL!: String) {this.model = modelthis.apiKey = apiKeythis.baseURL = baseURL}override public prop service: String {get() { "zhipuai" }}override public prop name: String {get() { model }}override public func create(imageReq: ImageRequest): ImageResponse {let req = JsonObject()req.put("model", JsonString(model))req.put("prompt", JsonString(imageReq.prompt))req.put("quality", JsonString("standard"))req.put("size", JsonString(imageReq.size))let header = HashMap<String, String>([("Content-Type", "application/json"),("Authorization", "Bearer ${this.apiKey}")])match (HttpUtils.post("${this.baseURL}/images/generations", header, req, verify: false)) {case Some(body) =>let resp = ZhipuAIImageResponse.fromJsonValue(JsonValue.fromStr(body))let image = resp.data[0] // Currently, we just return the first imagereturn ImageResponse(url: image.url)case None => throw ModelException("Fail to get image http response")}}
}
程序测试
测试程序编写如下：
package zhipuimgimport magic.dsl.tool
import magic.jsonable.*
import magic.tool.NativeFuncTool
import magic.core.model.ImageRequest
import magic.model.ModelManager
import magic.config.Configmain(): Int64 {let model = ModelManager.createImageModel("zhipuai:cogview-3-flash")
let resp = model.create(ImageRequest("夏天，沙滩，比基尼，躺椅",size: "1024x1024")
)
println("图像已经生成， URL：${resp.url}")
return 0
}这个程序和前面测试硅基流动的代码相同（使用华为CangjieMagic智能体框架实现文生图-CSDN博客） 。
测试结果如下：
developer@developer:~/IDEProjects/zhipuimg$ cjpm run --name zhipuimg
图像已经生成， URL：https://aigc-files.bigmodel.cn/api/cogview/20250615154053a589fe6d68174c19_0.pngcjpm run finished生成的图像如下，感觉比硅基流动的模型好一些：
结束语
通过本文的实践指南，我们不仅掌握了质谱AI文生图API的核心调用方法（包括模型选择、质量参数调优和尺寸定制），更成功解决了Cangjie Magic框架中的兼容性挑战：通过新增ZhipuAIImageModel模块，重构模型管理器，并实现专属响应解析逻辑。