BigModel API cURL Examples for Chat Completions

This guide shows how to call BigModel chat completions with cURL. It covers the minimum request, required headers, model and message parameters, non-streaming and streaming responses, and the checks that help diagnose authentication or model errors. The examples use the OpenAI-compatible gateway described by the existing BigModel integration flow: https://api.bigmodel.org/v1.

What you need before sending a request

• A BigModel API key stored outside your source code.
• The BigModel API base URL: https://api.bigmodel.org/v1.
• A model ID that is available to your account. Retrieve it from /v1/models instead of copying an old model name from a tutorial.

Set the API key in your shell

Put the key in an environment variable so it is not written directly into the command history or a source file:

export BIGMODEL_API_KEY="replace-with-your-api-key"
export BIGMODEL_API_BASE="https://api.bigmodel.org/v1"

List available models

Use the models endpoint to check authentication and obtain a current model ID:

curl "$BIGMODEL_API_BASE/models" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY"

Copy one of the returned data[].id values into the chat completion request. Model availability can depend on the account and current service configuration.

Minimum non-streaming chat completion

The smallest useful request is a POST with JSON content, a model, and a non-empty messages array:

curl "$BIGMODEL_API_BASE/chat/completions" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "messages": [
      {"role": "user", "content": "Explain what an API is in one sentence."}
    ],
    "stream": false
  }'

In a successful non-streaming response, read the generated text from choices[0].message.content. Keep the complete response while debugging so you can also inspect model and usage fields returned by the gateway.

Headers and request body

Required headers

• Authorization: Bearer <your-api-key> authenticates the request.
• Content-Type: application/json tells the endpoint to parse the request body as JSON.

Core parameters

• model: the model ID returned by /v1/models.
• messages: the conversation history, with each item containing a role and content.
• stream: use false for one complete JSON response or true for incremental output.
• temperature and max_tokens: optional generation controls when supported by the selected model. If a model rejects an optional field, remove it and retry with the documented fields for that model.

Adding a system message and generation options

For a more controlled request, add a system instruction and optional generation settings:

curl "$BIGMODEL_API_BASE/chat/completions" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "messages": [
      {"role": "system", "content": "Answer clearly and briefly."},
      {"role": "user", "content": "Give three practical uses for a chat completion API."}
    ],
    "temperature": 0.7,
    "max_tokens": 300,
    "stream": false
  }'

Start with the required fields first. Add optional parameters one at a time so an error can be traced to a specific field or model capability.

Streaming chat completions

Set stream to true when the client should receive the response incrementally. The response is delivered as Server-Sent Events, so -N helps cURL display chunks without buffering:

curl -N "$BIGMODEL_API_BASE/chat/completions" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_V1_MODELS",
    "messages": [
      {"role": "user", "content": "Write a short checklist for testing an API integration."}
    ],
    "stream": true
  }'

Streaming clients should read each data: event, parse the JSON payload, append any returned delta content, and stop when the stream sends the [DONE] marker. Do not treat each network chunk as a complete JSON object; one event can be split across multiple chunks.

Useful cURL checks

Show the HTTP status and response headers

curl -i "$BIGMODEL_API_BASE/chat/completions" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_V1_MODELS","messages":[{"role":"user","content":"Hello"}],"stream":false}'

Save the response for inspection

curl "$BIGMODEL_API_BASE/chat/completions" \
  -H "Authorization: Bearer $BIGMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID_FROM_V1_MODELS","messages":[{"role":"user","content":"Hello"}],"stream":false}' \
  -o bigmodel-response.json

Common problems

• 401 Unauthorized: check that the key is present, valid, and sent as Authorization: Bearer .... Also confirm the request is going to the /v1 gateway.
• 400 Bad Request: validate the JSON, make sure messages is not empty, and remove optional fields that the selected model does not accept.
• 404 or model errors: request /v1/models again and use an ID returned for the current account.
• 429 or 5xx: keep the response body and headers, then retry transient failures with a bounded backoff instead of sending an unlimited loop.
• No visible streaming output: use curl -N and make sure the client parses Server-Sent Events rather than waiting for one final JSON document.

Recommended request workflow

1. Export the API key and base URL in the shell.
2. Call /v1/models and choose a returned model ID.
3. Run the minimum non-streaming request.
4. Add optional parameters only after the basic request succeeds.
5. Switch to stream: true and parse the event stream when incremental output is useful.

FAQ

Do I need an SDK to call BigModel?

No. These examples use cURL and HTTPS directly. An SDK is optional; the important parts are the base URL, Bearer header, JSON body, and a model ID available to the account.

Where should the model value come from?

Use an ID returned by https://api.bigmodel.org/v1/models. This avoids relying on a model name that may be outdated or unavailable to the current account.

What is the difference between stream false and true?

stream: false returns one complete response, while stream: true returns incremental Server-Sent Events that the client must parse until [DONE].

Which headers are needed for a JSON chat request?

Send Authorization: Bearer <your-api-key> and Content-Type: application/json.

How should an API key be stored?

Keep it in an environment variable or a server-side secret manager. Do not hard-code it in source code, commit it to a repository, or print it in logs.