适用模型与响应类型

本页适用于 Pro Image、Flash Image、Flash Lite Image 及旧版 2.5 的原生 generateContent。它们返回 JSON 内容块，不是 Images API 的 data[].b64_json。Chat 返回格式见Chat 兼容调用；SSE 边界处理见流式消费。

鉴权与结果来源

使用请求头 Authorization: Bearer YOUR_API_KEY。将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的空格；基础地址为 https://top.qingyuntop.ai。

图片随文生图或编辑请求直接返回。解码本地 response.json 不再发送 API 请求，也不需要另一个下载 Token。

响应字段

字段与类型位置、填写规则与限制
candidates；object[]响应顶层候选数组；可能缺省或为空，不把 HTTP 200 单独视为生图成功。遍历各候选的 content.parts。
candidates[].content；object候选的完整 model 内容；parts 中可能混合 text、inlineData 和思考块。多轮请求保存并回传整个对象。
candidates[].finishReason；string可缺省，流式通常在后续事件出现。STOP 为正常结束；MAX_TOKENS、SAFETY、IMAGE_SAFETY、NO_IMAGE、IMAGE_OTHER 等需结合正文排查。
promptFeedback；object响应顶层可选对象。输入被拦截时检查 blockReason；可能没有 candidates。不要仅因状态码 200 自动重试。
usageMetadata；object响应顶层可选对象。可能包含 promptTokenCount、candidatesTokenCount、thoughtsTokenCount、totalTokenCount 及模态明细；是用量信息，不是人民币费用。
modelVersion；string响应顶层可选字段；模型实际版本，适合与请求时间一起记录，不能替代请求路径中的模型选择。
responseId；string响应顶层可选标识；供追踪与排错。本目录不提供用它查询任务、续传、下载或取消的接口。

每个 content.parts[] 可以包含：text 文字说明、inlineData.mimeType 图片类型、inlineData.data Base64 图片，或 thought=true 的思考内容。thoughtSignature 可能附在文本/图片块上，供多轮回传使用。展示最终结果时跳过思考块，保存完整历史时不破坏原始块顺序与签名关联。

下面为结构示意，图片字节是一张用于说明解码的 1×1 PNG，不是实际生图结果；可选用量与签名字段未展示：

{
  "candidates": [
    {
      "index": 0,
      "content": {
        "role": "model",
        "parts": [
          {"text": "图片结构示意。"},
          {"inlineData": {"mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+j5k0AAAAASUVORK5CYII="}}
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

如何判断生成成功

先检查 HTTP 状态和 error，再检查 promptFeedback.blockReason。输入可能被拦截且没有候选。对返回候选检查 finishReason：正常结束为 STOP；若有长度限制、安全限制或无图片原因，保留正文排查。最后确认实际存在非思考图片并能成功解码，不能只检查有无 candidates[0]。

不要固定读取 parts[0].inlineData；第一个块可能是文字或思考内容。也不要把多个图片块的 Base64 拼成一个文件；每个图片块分别保存，根据 MIME 选择 .png、.jpg 或 .webp。

cURL 结果的本地解码

各页 Python/Node.js 示例已经包含保存逻辑。若使用 cURL，可在 response.json 所在目录运行下面的 Python 3 脚本；只使用标准库，不发起网络调用。原始 JSON 应保留，以便多轮编辑。

import base64
import json
from pathlib import Path

result = json.loads(Path("response.json").read_text(encoding="utf-8"))
if result.get("error") or (result.get("promptFeedback") or {}).get("blockReason"):
    raise RuntimeError("生成未成功，请检查响应中的 error 或 promptFeedback")
extensions = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}
count = 0
for candidate in result.get("candidates", []):
    if candidate.get("finishReason") != "STOP":
        raise RuntimeError(f"生成未正常结束: {candidate.get('finishReason')}")
    for part in (candidate.get("content") or {}).get("parts", []):
        if part.get("thought") or not part.get("inlineData"):
            continue
        image = part["inlineData"]
        extension = extensions.get(image.get("mimeType"))
        if not extension:
            raise RuntimeError("未知的输出图片类型，请检查完整响应")
        count += 1
        Path(f"output-{count}.{extension}").write_bytes(base64.b64decode(image["data"], validate=True))
if count == 0:
    raise RuntimeError("没有图片，请检查文字说明、模型和安全反馈")
print(f"已保存 {count} 张图片")

查询、下载和错误边界

本目录没有按 responseId 查询、下载、取消或恢复的任务接口。Base64 已包含图片，不需要等待 URL 生效，也没有本页承诺的远程下载链接有效期。请在业务中保存所需图片和追踪信息。

响应被日志、数据库字段或界面复制截断后会导致 Base64 无法解码。使用完整响应文件，避免把文字解释、Markdown 外壳或 data URI 前缀混入原生 Base64。超时或断线不等于生成已取消；详见错误排查。官方参考：GenerateContentResponse。