Polling, Callback, and Streaming: What’s the Difference?

Your AI large model image generation API — how long does it take to produce results? After a request is sent, it can take as little as 5 seconds or as long as 30 seconds. Do you really have to keep waiting for minutes for it to return?

Waiting for one or two requests is fine, but as your user base grows and image generation demand surges, with hundreds or thousands of users generating content simultaneously, the question of “how to wait for the result” directly determines whether your system can handle the load.

At this point, you need to carefully consider one question: How should the action of “waiting for the result” be designed?

Should the client keep asking “Is it ready yet?” (polling)? Or should the server proactively notify the client “Come get the image” once generation is complete (callback)? Or should the data flow like a stream, pushing progress and results to the client as they are generated (streaming response)?

What problems do these three approaches solve respectively? In high-latency, high-concurrency scenarios like AI image generation, how should you choose and implement them?

I. What Problems Do Polling, Callback, and Streaming Response Solve Respectively

Polling — Repeatedly asking “Is it ready yet?” (Recommended)

Polling: The client holds an ID and actively queries the server every few seconds to ask “Is it ready yet?” It’s crude but universal.

For example, you submit an image generation request, and the backend tells you “It will take a while.” You don’t know when it will finish — what do you do? The simplest and most straightforward method: Send a request every few seconds asking — “Is it done? Is it done?” — until the backend returns a “completed” flag, at which point you stop querying.

Callback: Leave an address, and contact me when it’s done

Callback: Once generation is finished, the server proactively sends a request to the address you specified, telling you “Come get the image.” It’s efficient, but requires you to have a publicly accessible server.

The idea of a callback is the opposite — don’t keep asking repeatedly. Tell me in advance who should receive the result and what to do next; I’ll contact you proactively when I’m done.

However, if your server crashes, you may fail to receive the returned content! This needs attention.

Streaming Response — Words popping out one by one

Streaming Response: The server pushes progress and results to the client bit by bit, like a flowing stream.

Streaming responses are different from the two above. Polling and callbacks care about “when the task ends,” while streaming cares about “how the process and results of the task are gradually displayed to the user.”

If you’ve used ChatGPT, you know that when it answers questions, the text appears character by character — that’s a streaming response.

Streaming also has drawbacks: The server needs to maintain long connections. If there are too many concurrent users, the server’s memory and connection count will face significant pressure. Additionally, client-side code is more complex than ordinary requests; it must handle data fragmentation, protocol parsing, disconnection and reconnection, and so on.

II. How to Integrate Grsai API’s Callback and Polling Models

GrsaiAPI (https://grsai.com) is a domestic source API provider offering affordable and stable AI large model API services. Models include Nano banana pro, Nano banana2, Nano banana 2 lite, Gpt image 2, gemini 3.1 pro….. image and language models. It supports OpenAI, Gemini protocol, and responses-api protocol calls. Model list: https://grsai.com/dashboard/models

Currently there are old and new documentation — how to choose? The new documentation is strongly recommended. Nano banana and GPT image models use a unified interface, but only support asynchronous polling. The old documentation has different interfaces for Nano banana and GPT; models cannot be mixed or tasks will get stuck, and it supports both callback webhook parameters and polling.

New documentation: https://qmy27nhsd9.apifox.cn/452409577e0 (Banana GPT unified interface address)
Old documentation: https://grsai.com/dashboard/documents/nano-banana (Banana GPT interface addresses are different)

Below is a detailed explanation of the different query methods for the two documentations.

Grsai API Old Version Documentation: WebHook Callback + Polling Dual Mode

In the Grsai API old version documentation, the Nano banana model interface uses /v1/draw/nano-banana, while GPT image generation uses /v1/draw/completions. The callback control parameter is webHook.

The logic is as follows:

Use POST request header configuration:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer apikey" // apikey should be filled with the secret key created on the Grsai console Apikey page, a code starting with sk.
}

Grsai API interface addresses: Note that banana models must use the banana interface, and GPT models must use the GPT interface. Do not call banana models with the GPT interface, or the task will get stuck in progress! The parameters of the two documentations are also different.

Banana request address: https://https://grsaiapi.com/v1/draw/nano-banana  
GPT request address: https://https://grsaiapi.com/v1/draw/completions

Callback request parameter usage:

{
  "model": "nano-banana-pro", // model
  "prompt": "prompt", // prompt
  "aspectRatio": "auto", // size
  "imageSize": "1K", // resolution
  "urls": [
    "https://example.com/example.png" // reference image link
  ],
  "webHook": "https://example.com/callback", // your server address
  "shutProgress": false // progress is enabled by default; set to true to disable progress
}

You pass this address to Grsai, then go about your business. When the image is generated, Grsai will proactively send an HTTP request to this address and push the final result JSON data to you. Although callbacks are convenient and effortless, if your server has problems and cannot receive the callback results in time, it becomes troublesome. You will need to re-query the results via the “get result interface” /v1/draw/result.

Return result

{
  "id": "xxxxx", // task id
  "results": [
    {
      "url": "https://example.com/example.png", // image link
    }
  ],
  "progress": 100, // task progress
  "status": "succeeded", // task status: "running": in progress, "succeeded": success, "failed": failure
  "failure_reason": "", // failure reason "output_moderation": output violation, "input_moderation": input violation, "error": other error
  "error": "" // official returned error reason
}

Polling request parameter usage:

{
  "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", // If not using callback but using the polling result interface method to get results, the interface needs to immediately return an id, so set the webHook parameter to "-1", and an id will be returned immediately
  "shutProgress": false
}

Return result:

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": "id" // use this id to poll result
  }
}

Set webHook to “-1” → immediately returns task id, then call the /v1/draw/result interface to poll.

Request address: https://https://grsaiapi.com/v1/draw/result

Polling interface request parameter usage:

{
  "id": "xxxxx" // only need the id returned by webhook
}

Return result

{
  "code": 0,
  "data": {
    "id": "xxxxx",
    "results": [
      {
        "url": "https://example.com/example.png", // image link
        "content":""
      }
    ],
    "progress": 100,
    "status": "succeeded", 
    "failure_reason": "",
    "error": ""
  },
  "msg": "success" // task status
}

Old interface users can choose as needed and support both polling and callback, but different large models correspond to different interface addresses, making management troublesome.

Grsai API New Version Documentation: Polling Only, Controlled by replyType (Recommended)

The Grsai API new version interface has been changed to /v1/api/generate. Image models are called uniformly and the parameters are also different from the old version documentation. There is no longer a webHook parameter; instead, there is replyType, which has three values:

Asynchronous generation interface query documentation: qmy27nhsd9.apifox.cn/452418916e0

The new version directly removed support for WebHook callbacks, retaining only polling and streaming. This is to avoid users being unable to receive callback results due to server lag.

The logic is as follows:

Polling: Set the input parameter replyType to “async”. The interface immediately returns an id, which you then use to call /v1/chat/completions to poll for results.

Use POST request header configuration:

{
  "Authorization": "Bearer apikey" // apikey should be filled with the secret key created on the Grsai console Apikey page, a code starting with sk.
}

Grsai API new documentation interface address: Only supports image models

Banana GPT image model request address: 
https://https://grsaiapi.com/v1/api/generate

Callback request parameter usage:

{
  "model": "gpt-image-2", // model name must be consistent with the Grsai model list
   "prompt": "Generate a screenshot of Border Collies and Old English Sheepdogs live-streaming sales on Douyin.", // prompt
   "images": [], // reference image parameter is different from the old documentation
   "aspectRatio": "1024x1024", // GPT fills in detailed resolution, Nano banana fills in ratio
   "replyType": "async" // (asynchronous polling)
}

Return result:

{
    "id": "xxxx", // polling id
    "status": "running"
}

Set replyType to “async” → immediately returns task id, then call the /v1/api/result interface to poll.

Request address: https://https://grsaiapi.com/v1/api/result

Polling interface request parameter usage:

{
  "id": "xxxxx" // the returned id
}

Return result:

{
    "id": "xxx", // task id
    "status": "succeeded", // generation status
    "results": [
        {
            "url": "xxx", // image link
            "content":""
        }
    ]
}

III. Summary

It is recommended to use the GrsaiAPI new interface asynchronous polling. The old interface will not become invalid either — choose a suitable solution according to your application scenario.

If you pursue simplicity and stability: Directly use replyType: “async” polling, combined with the /v1/api/result interface to check results. The maximum timeout for Grsai Api generation tasks is half an hour.

If it is an internal system and you have a public server: You can refer to the old version WebHook approach, build a unified callback gateway yourself, and after receiving the result, push it to the frontend via WebSocket. Note that once your server has problems, you will be unable to receive callback results and will need to obtain data via the query interface.

Whether polling, callback, or streaming — any choice is fine. The key is not to leave yourself and users waiting idly. Grsai Api supports high concurrency, so feel free to implement concurrency with queues!