AI图片生成API实战：提示词、参考图与异步任务处理

AI生图接口通常不是同步返回图片，而是先创建任务、再查询结果。轻语 imageGeneration 支持文生图、参考图编辑和模型选择，适合电商素材、海报草图和产品概念图工作流。

一、请求模型与参数

参数	说明	使用建议
prompt	生成或编辑提示词	描述主体、风格、构图和限制条件
model	gpt-image-2或nano-banana-2	按质量、速度和成本选择
size	比例或像素尺寸	与投放渠道的画布比例一致
image	参考图Data URL数组	服务端转换并限制输入大小
imageSize	1K、2K或4K	按最终用途选择清晰度

二、创建生图任务

const response = await fetch('https://5555api.com/data/api/imageGeneration', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    apikey: process.env.QINGYU_API_KEY,
    prompt: '适合产品详情页的极简摄影图，白色背景，柔和侧光',
    model: 'gpt-image-2',
    n: 1,
    size: '1:1',
    imageSize: '2K'
  })
});
const created = await response.json();
if (created.code !== 200 || !created.data?.task_id) {
  throw new Error(created.msg || '创建生图任务失败');
}

三、参考图编辑与提示词

参考图编辑时，先将图片转换成Data URL，再放入 image 数组。提示词应明确“保留什么、修改什么、输出尺寸和风格”，不要只写一个模糊的动作词。客户端上传的图片应先在服务端压缩和校验。

const body = {
  apikey: process.env.QINGYU_API_KEY,
  prompt: '保留主体轮廓，将背景替换为浅灰色工作室场景',
  model: 'gpt-image-2',
  image: [referenceImageDataUrl]
};

四、轮询任务结果

async function waitForImage(taskId) {
  for (let attempt = 0; attempt < 100; attempt += 1) {
    await new Promise(resolve => setTimeout(resolve, 3000));
    const query = new URLSearchParams({
      apikey: process.env.QINGYU_API_KEY,
      task_id: taskId
    });
    const result = await fetch(
      'https://5555api.com/data/api/imageGeneration/status?' + query
    ).then(response => response.json());
    if (result.code !== 200) throw new Error(result.msg || '查询失败');
    const task = result.data;
    const image = task?.data?.[0]?.url || task?.data?.[0]?.b64_json;
    if (image) return image;
    if (task?.status === 'failed' || task?.error) throw new Error('生图失败');
  }
  throw new Error('生图任务超时');
}

五、上线前的安全与成本控制

服务端保存API Key，前端只提交业务提示词。
限制单次图片数量、提示词长度和参考图大小。
记录task_id和扣费信息，避免用户重复点击创建任务。
生成结果及时转存，按业务策略清理临时图片。

六、进一步阅读

参数、模型编码和完整示例请查看AI生图与图片编辑API文档。如果业务还需要文字处理，可以结合AI聊天API接入指南先生成提示词，再提交图片任务。

常见问题

imageGeneration支持哪些模式？

接口支持只传prompt的文生图，也支持通过image数组传入参考图Data URL进行参考图生成或图片编辑。

如何查询AI生图结果？

创建任务后保存task_id，使用GET /data/api/imageGeneration/status并携带apikey和task_id查询状态与最终图片。

API Key可以放在前端吗？

不建议。生图接口会产生计费，正式Key应放在服务端，由服务端代理前端请求并限制提示词和图片大小。

结语

AI图片生成API的关键是把提示词、参考图和异步状态管理拆开设计。先创建、后查询、最后转存结果，配合服务端密钥和成本限制，才能把一次演示变成稳定的生产能力。