别傻等着了！轮询、回调、流式到底啥区别？

你的 AI 大模型生图 API，多久才能出结果？一个请求发出去，少则 5 秒，多则 30 秒，几分钟难道要一直等它返回吗？

一两个可以的等，但随着你的用户量增加模型生图需求暴涨，同时有几百上千个用户在生成内容，那 “怎么等结果” 这个问题，就直接关系到你的系统能不能扛得住。

这时候，你就得认真想清楚一个问题：“等结果” 这个动作，到底该怎么设计？

是让客户端一遍遍来问 “好了没”？（轮询）还是让服务端生成完了主动告诉客户端 “来取图”？（回调）又或者是让数据像流水一样，一边生成一边往客户端推？（流式响应）

这三种方案，分别解决什么问题？在 AI 生图这种高耗时、高并发的场景下，又该怎么选、怎么搭？

轮询，回调，流式响应分别解决什么问题

轮询——一遍一遍去问 “好了没”（推荐）

轮询（Polling）：客户端拿着 id，自行设置每隔几秒主动问一次服务器 “好了没”。笨但也通用。

比如你提交了一个生图请求，后端告诉你 “得跑一会儿”。你不知道啥时候跑完啊，怎么办？最简单粗暴的办法：每隔几秒就发一次请求去问——“跑完了没？跑完了没？” 直到后端给你返回一个 “完成” 的标记，你才停止询问。

回调：留个地址，完事了找我

回调（Callback）：生成完了，服务端主动往你指定的地址发个请求，告诉你 “来取图”。高效，但需要你有个公网能访问的服务器。

回调的思路正好反过来——你别一遍遍去问了，你把结果要交给谁、后续要干啥，提前告诉我，我干完了主动找你。

但是如果你的服务器崩了，就会出现收取不到返回内容的情况！这个要注意。

流式响应——字一个个蹦出来

流式响应（Streaming）：服务端像流水一样，把进度和结果一点点推给客户端。

流式响应跟上面两种都不太一样。轮询和回调关心的是 “任务什么时候结束”，而流式关心的是 “任务的过程和结果怎么逐步展示给用户”。

你用过 ChatGPT 就知道了，它回答问题时是一个字一个字往外蹦的，那就是流式响应。

流式的缺点也有：服务端需要维持长连接，如果并发用户太多，服务端的内存和连接数压力会比较大。另外，客户端代码比普通请求复杂一些，得处理数据分片、解析协议、处理断线重连等情况。

如何对接 Grsai APi 的回调和轮询模型

GrsaiAPi（grsai.com）是国内源头 Api 供应商，提供便宜稳定的 Ai 大模型 api 服务。模型包含 Nano banana pro，Nano banana2，Nano banana 2 lite，Gpt image 2，gemini 3.1 pro.....图片和语言模型。支持 openai、Gemini 协议、responses-api 协议调用。

目前分为新旧文档怎么选择？首推新文档，nano banana 和 gpt 画图模型统一接口，但只支持异步轮询。旧文档 nano banana 和 gpt 接口不一样，模型不可以混用会导致任务卡死，支持回调 webhook 参数和轮询。

• 新文档：qmy27nhsd9.apifox.cn/452409577e0（香蕉 gpt 统一接口地址）
• 旧文档：grsai.com/zh/dashboard/documents/nano-banana（香蕉 gpt 接口地址不同）

针对两个文档不同的查询方式，下面展开说说。

Grsai APi 旧版文档：WebHook 回调 + 轮询双模式

Grsai APi 旧版文档 Nanobanana 模型接口走的是 /v1/draw/nano-banana，gpt 画图是/v1/draw/completions 回调控制参数是 webHook。

逻辑是这样的：

• 回调： webHook 地址，生成完成后，服务端就把结果 POST 到你那个地址上，你被动接收就行。
• 轮询：把 webHook 填成 "-1"，接口就立即返回一个 id，你再拿着这个 id 去调用 /v1/draw/result 接口轮询结果。

使用 post 请求头部配置：

{
  "Content-Type": "application/json",
  "Authorization": "Bearer apikey" //apikey填Grsai控制台Apikey页面创建的秘钥，sk开头的编码。
}

Grsai APi 接口地址：注意使用香蕉模型用香蕉接口，gpt 模型用 gpt 接口，不可以用 gpt 接口调用香蕉模型，会导致任务卡死在进行中！而且两个文档参数也不同。

香蕉请求地址：https://grsai.dakka.com.cn/v1/draw/nano-banana  
gpt请求地址：https://grsai.dakka.com.cn/v1/draw/completions 

回调请求参数用法：

{
  "model": "nano-banana-pro",//模型
  "prompt": "提示词",//提示词
  "aspectRatio": "auto",//尺寸
  "imageSize": "1K",//分辨率
  "urls": [
    "https://example.com/example.png"//参考图链接
  ],
  "webHook": "https://example.com/callback",//你的服务器地址
  "shutProgress": false //默认打开进度，取消进度填true
}

你把这个地址传给 Grsai，然后该干嘛干嘛去。等图片生成好了，Grsai 那边会主动往你这个地址发一个 HTTP 请求，把最终结果 json 数据给你推过来。回调虽然很方便省事但是如果你的服务器除了问题无法及时收到回调的结果就会比较麻烦，需要通过 “获取结果接口”/v1/draw/result 重新查询一次结果。

返回结果：

{
  "id": "xxxxx",//任务id
  "results": [
    {
      "url": "https://example.com/example.png",//图片链接
    }
  ],
  "progress": 100,//任务进度
  "status": "succeeded", //任务状态："running": 进行中，"succeeded":成功，"failed": 失败
  "failure_reason": "",//失败原因"output_moderation": 输出违规，"input_moderation": 输入违规，"error": 其他错误
  "error": ""//官方返回的报错原因
}

轮询请求参数用法：

{
  "model": "nano-banana-pro",
  "prompt": "An incredibly cute little orange cat, fluffy and with its big, round eyes curiously staring at the camera, sits on a sun-drenched wooden windowsill. The background features greenery and a small bookshelf. The professional lighting and ultra-high-definition realistic style showcases rich detail.",
  "aspectRatio": "1:1",
  "imageSize": "2K",
  "urls": [],
  "webHook": "-1", // 如果不使用回调，而使用轮询result接口方式获取结果，需要接口立即返回一个id，则webHook参数填"-1"，那么会立即返回一个id
  "shutProgress": false
}

返回结果：

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "id" //用这个id轮询result
  }
}

webHook 填 "-1" → 立即返回任务 id，再调用 /v1/draw/result 接口轮询。

请求地址：https://grsai.dakka.com.cn/v1/draw/result

轮询接口请求参数用法：

{
  "id": "xxxxx" //只需要一个webhook返回的id
}

返回结果：

{
  "code": 0,
  "data": {
    "id": "xxxxx",
    "results": [
      {
        "url": "https://example.com/example.png",,//图片链接
        "content":""
      }
    ],
    "progress": 100,
    "status": "succeeded", 
    "failure_reason": "",
    "error": ""
  },
  "msg": "success"//任务状态
}

旧接口用户可以按需选择同时支持轮询和回调，但是不同大模型对应接口地址不同，管理麻烦。

Grsai APi 新版文档：：只用轮询，通过 replyType 控制（推荐）

Grsai Api 新版接口改成了 /v1/api/generate，图片模型统一调用并且参数也和旧版文档不同。不再有 webHook 参数，取而代之的是 replyType，有三个取值：

• replyType: "json"：同步请求，任务完成后一次性把完整的 JSON 响应返回。
• replyType: "stream"：流式返回，可以实时拿到进度。
• replyType: "async"：异步轮询，立即返回任务 id 和 status: running，然后你需要拿着这个 id 去异步查询接口/v1/chat/completions 轮询结果。
• 异步生成接口查询文档：qmy27nhsd9.apifox.cn/452418916e0

新版直接砍掉了 WebHook 回调的支持，只保留了轮询和流式。为了避免用户服务器卡顿导致无法收到回调结果。

逻辑是这样的：

轮询：入参的 replyType 填 "async"，接口就立即返回一个 id，你再拿着这个 id 去调用 去/v1/chat/completions 轮询结果。

使用 post 请求头部配置：

{
  "Authorization": "Bearer apikey" //apikey填Grsai控制台Apikey页面创建的秘钥，sk开头的编码。
}

Grsai APi 新文档接口地址：仅支持图片模型

香蕉gpt画图模型请求地址：https://grsai.dakka.com.cn/v1/api/generate

回调请求参数用法：

 {
  "model": "gpt-image-2",//模型名称需要和Grsai模型列表一致
   "prompt": "Generate a screenshot of Border Collies and Old English Sheepdogs live-streaming sales on Douyin.",//提示词
   "images": [],//参考图参数和旧文档不一样
   "aspectRatio": "1024x1024",//gpt填详细分辨率，Nano banana填比例
   "replyType": "async"//（异步轮询）
}

返回结果：

{
    "id": "xxxx",//轮询id
    "status": "running"
}

replyType 填 "async" → 立即返回任务 id，再调用 /v1/api/result 接口轮询。

请求地址：https://grsai.dakka.com.cn/v1/api/result

轮询接口请求参数用法：

{
  "id": "xxxxx" //返回的id
}

返回结果：

{
    "id": "xxx", //任务id
    "status": "succeeded",//生成状态
    "results": [
        {
            "url": "xxx", //图片链接
            "content":""
        }
    ]
}

六、最后总结

推荐使用 GrsaiApi 的新接口异步轮询，旧接口也不会失效，根据自己应用场景选一个合适的方案即可。

• 如果追求简单稳定：直接上 replyType: "async" 轮询，配合/v1/api/result 接口查结果，Grsai Api 生成任务最大超时时间为半小时。
• 如果是内部系统，且有公网服务器：可以参考旧版 WebHook 的思路，自己搭一个统一的回调网关，收到结果后再通过 WebSocket 推给前端。需要注意一旦你的服务器出问题就会无法接收到回调结果需要用查询接口获取数据。

轮询、回调、流式，选哪个都行，关键是别让自己和用户在那儿干等着，Grsai Api 支持高并发所以你放心大胆的用队列实现并发吧！