A user uploads a document and clicks “Analyze.” Your application sends it to a GLM model, but the browser stops waiting before the result arrives. The user clicks again. Now there may be two billable requests, neither connected cleanly to the page they are watching.
Moving the work into the background can improve this experience. It also creates a new responsibility: your application must remember which task belongs to which user, where it was submitted, and how to retrieve its result after a restart.
The central design question is therefore larger than how to make an asynchronous HTTP call. It is how to preserve one logical job while network connections, workers, and browser sessions come and go.
BigModel documents a native asynchronous Chat Completions endpoint that returns a task identifier, followed by a separate result query. That is the provider workflow examined here. The examples use its documented HTTP routes; they are not evidence that every GLM proxy exposes those routes. 智谱AI开放文档
This distinction matters when evaluating Treerouter or another model API relay. Confirm support for the exact model, submission endpoint, and retrieval endpoint together. Normal Chat Completions compatibility alone does not establish native asynchronous-job compatibility.
Before the upload: decide who owns the background job
“Async” describes several different things in model integrations. Choosing the wrong meaning can produce an application that looks asynchronous in code but still loses work when a process exits.
| Mechanism | What becomes asynchronous | What your application still needs |
|---|---|---|
| An asynchronous HTTP client | The local process can do other work while awaiting a response | Durable ownership if the process or connection disappears |
| Streaming chat | Output arrives incrementally over an open response | Stream handling and a plan for interruption |
| Native provider async task | Submission and result retrieval are separate requests | Persistent task identity and a retrieval worker |
| Application queue plus ordinary chat | Your own worker performs a normal model request later | Queue durability, worker recovery, and result storage |
| Batch processing | A collection of submitted requests is processed as a batch | Batch-specific submission and output handling |
These mechanisms can coexist, but they are not interchangeable API contracts. The official BigModel Batch guide describes a separate workflow. Do not send a batch file to a single-task endpoint or assume that a task identifier can be queried using a batch-results route.
For an interactive explanation that should appear word by word, review GLM streaming behavior. For a document report the user can collect later, a durable job may be a better fit. The choice follows the product experience, not the presence of an async keyword in a library.
Also identify the service surface. The Z.AI Chat Completions reference and BigModel’s domestic API documentation describe their respective endpoints. A normal-chat example on one service does not establish an identical native async route on the other. Keep credentials, base URL, and documentation from the same service together.
If your chosen Treerouter route supports ordinary chat but not provider-native async chat, the application-queue design remains available. Your worker calls the supported model route and stores the answer; the browser polls your application. In that architecture, your application owns the job ID. Do not present it as a BigModel task ID or invent a gateway polling endpoint.
The first receipt: save the identity before showing progress
Return to the document upload. Before sending a provider request, create a local job record. Associate it with the authenticated user and the exact input revision. A checksum can help distinguish a repeated click from a genuinely changed document, but do not use a checksum alone as an authorization boundary.
The record should answer a future operator’s basic questions without requiring the original worker to remain alive:
- Which application job and user own this work?
- Which model and service route were selected?
- Which input revision was submitted?
- Which non-secret credential reference identifies the account?
- Has a provider task ID been received and saved?
- Has the final result already been delivered?
Store a reference to your secret-management system, not the raw API key in the job row. A job may outlive a key rotation. The retrieval process should obtain valid credentials for the appropriate account through your normal credential-management path.
BigModel’s HTTP integration guide documents its base URL and Bearer authentication. On that service, native async chat submission uses POST /api/paas/v4/async/chat/completions. The request includes a supported model and messages; the response provides the generated task id and its status.
A submission can also carry a client request_id. Use it to correlate your logs, but do not assume it is an idempotency key. A documented request identifier is not, by itself, a guarantee that repeating a POST will reuse the same task or avoid a second charge. 智谱AI开放文档
This difference becomes important during a timeout. If the connection fails after submission, the provider may have accepted the job even though your application never received the receipt. Mark that local outcome as uncertain and investigate using the evidence available. Automatically repeating the POST converts uncertainty into a possible duplicate.
Once a response contains a provider task ID, save it transactionally before telling the browser that the job is available for tracking. A worker restart between displaying progress and saving the ID should not strand a result your user expects to receive.
For the basic model connection, the GLM API integration walkthrough is a useful starting point. Add job persistence only after the exact route can complete a small representative request.
While the user is away: retrieve without resubmitting
BigModel’s asynchronous-result reference documents GET /api/paas/v4/async-result/{id} and the task states PROCESSING, SUCCESS, and FAIL. 智谱AI开放文档
Treat those as provider task states. Your application may additionally need local states such as “waiting to submit,” “submission outcome unknown,” or “result awaiting validation.” Keep the two sets separate so that a local network failure does not falsely become a provider failure.
The following Python example retrieves an existing BigModel task. It deliberately contains no submission function. Re-running it with the same saved ID performs more retrieval requests rather than creating another generation job.
Install requests, then set BIGMODEL_API_KEY and GLM_TASK_ID through your normal environment or secret injection mechanism. Use an ID created on the matching BigModel service and account.
import os
import time
from urllib.parse import quote
import requests
def wait_for_result(session, task_id, key, wait_seconds=120):
deadline = time.monotonic() + wait_seconds
url = (
"https://open.bigmodel.cn/api/paas/v4/async-result/"
+ quote(task_id, safe="")
)
while True:
remaining = deadline - time.monotonic()
if remaining <= 0:
raise TimeoutError("Polling paused; retain the existing task ID")
response = session.get(
url,
headers={"Authorization": f"Bearer {key}"},
timeout=min(15, remaining),
allow_redirects=False,
)
if response.status_code != 200:
raise RuntimeError(f"Retrieval HTTP status: {response.status_code}")
result = response.json()
state = result.get("task_status")
if state == "SUCCESS":
return result
if state == "FAIL":
raise RuntimeError("Provider reported a failed task")
if state != "PROCESSING":
raise RuntimeError("Unexpected task status; inspect the response")
remaining = deadline - time.monotonic()
if remaining > 0:
time.sleep(min(3, remaining))
if __name__ == "__main__":
with requests.Session() as session:
result = wait_for_result(
session, os.environ["GLM_TASK_ID"],
os.environ["BIGMODEL_API_KEY"],
)
print({"id": result.get("id"), "status": result.get("task_status")})This is a small retrieval example, not a durable job scheduler. Its waiting budget is a local polling policy, not a cancellation request. A Requests timeout also measures connection or read waiting rather than guaranteeing a strict wall-clock limit for an entire operation. Production scheduling needs its own deadline and recovery policy. Requests 2.34.2 documentation
If retrieval raises an HTTP or network error, preserve the task ID. A failed GET does not establish that generation failed. Consult the BigModel error-code reference, classify the problem, and decide whether retrieval can resume after credentials, service availability, or throttling conditions change.
Avoid putting a tight polling loop into every browser tab. A central worker can poll once and update your job record; several clients can then read the same application status. This makes provider traffic easier to control and prevents a page refresh from becoming a new task controller.
For many active jobs, schedule the next retrieval time instead of keeping one sleeping worker per task. Bound polling concurrency and add appropriate spacing. The GLM concurrency and capacity guide provides related planning context, but native async submission should not be treated as an exemption from service limits.
When the result arrives: finish the business operation once
SUCCESS means the provider reports a successful task. Your product may still need to validate the returned answer before calling the document analysis complete.
Suppose the requested report must include a document identifier, an executive summary, and three cited findings. Check those requirements explicitly. If your application requires structured JSON, parse and validate the payload rather than trusting prose that merely resembles the requested structure.
Inspect the returned choices and completion information appropriate to the request. A tool-call response needs an application tool-execution step; it is not automatically a finished report. If your workflow includes tools, the GLM tool-history guide explains why keeping the relevant conversation sequence matters.
Store the provider result and the validation outcome separately. This preserves evidence when a technically successful generation fails your product’s acceptance criteria. It also makes it possible to improve validation without submitting the same document again immediately.
Make delivery idempotent at the application layer. For example, use a transaction and a uniqueness constraint keyed to the application job so that two workers observing the same completed task do not both publish a report or send a notification. A repeated retrieval is not the same event as a new business result.
Retain useful operational measurements: time submitted, time the receipt was saved, time success was observed, token usage when supplied, and the model route. Distinguish observed completion time from actual provider completion time; a polling interval can introduce a gap between them.
Do not promise that native async processing makes GLM faster or cheaper. Its immediate benefit is separating submission from retrieval. Judge the integration by recoverability, user experience, and measured completion cost for accepted reports.
The release rehearsal: close the browser and restart the worker
Before opening the feature to customers, perform the failure tests that a happy-path demo avoids. Use synthetic documents and a small spending limit.
First, close the browser after submission. Reopen the application and verify that the same user can find the existing job without triggering another POST. Then restart the worker after the provider ID is saved and confirm that retrieval resumes from persistent storage.
Next, simulate a retrieval error. The application should retain the saved identity and display an accurate status rather than declaring the model job failed. Separately simulate an uncertain submission result and verify that your code does not blindly create another task.
Finally, let two workers observe a completed result. Confirm that your application stores and delivers it once. These checks exercise the job design, while the model API acceptance-test guide covers broader questions about output quality and route behavior.
If you prefer an SDK to raw HTTP, start from the official BigModel Python SDK guide and verify the methods exposed by the installed version. An SDK can simplify requests; it does not replace persistent job ownership or establish which endpoints a third-party relay supports.
When considering Treerouter, first inspect its model directory. Confirm the exact GLM route and the required API operations. Then create an evaluation account for a small integration test using either verified native async support or an application-owned background worker over supported chat.
The useful milestone is concrete: one user action creates one tracked job, a worker can recover its progress, and the user receives one validated result. That is the experience worth taking into production.






