OpenAI SDK

OpenAI's official Python and TypeScript SDKs support custom base URLs. After pointing the client to https://api.agtcloud.cn/v1, you can use the same SDK method to call AGTCloud's Chat Completions and Responses compatible entry.

This page is intended for server-side applications. Browser front-ends, desktop application installation packages, and mobile code cannot securely store long-term API keys, so you should not directly create OpenAI clients with real credentials.

Choose Chat or Responses

Both entry points use the same AGTCloud API Key, but the scope of model support may differ. Please check the protocols supported by the model in the Model Marketplace and replace the MODEL_ID in the example with the full model ID.

Preparation

Before you start, please confirm that you have:

• Create the AGTCloud API Key on the API Keys page;
• Prepare model IDs supporting Chat Completions or Responses;
• Prepare a trusted server runtime with Python 3.10+ or Node.js 22+;
• Use a dependency lock file, and do not allow uncontrolled SDK upgrades in production.

Operating environment requirements may vary depending on the SDK version. Before upgrading the SDK, please also check the current official support scope and the deployment environment of your project.

Install the SDK

python -m pip install openai

After installation, write the actual resolved SDK version into the project lock file. When upgrading the version, re-verify client initialization, response type, and streaming processing logic.

Configure the API Key

Provide API keys through server-side environment variables. The following values are secure placeholders only; in production, you can use a managed secrets service instead.

export AGTCLOUD_API_KEY="your-api-key"

Create the OpenAI client

Set the client Base URL to https://api.agtcloud.cn/v1. Do not enter only the API Origin or append /chat/completions or /responses; the SDK adds the endpoint path for the method you call.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGTCLOUD_API_KEY"],
    base_url="https://api.agtcloud.cn/v1",
)

Use Responses

Responses accepts text or Typed Items through input. A successful response includes status, Output Items, and token usage. The SDK provides output_text to aggregate text from the response.

response = client.responses.create(
    model="MODEL_ID",
    instructions="Please answer concisely and accurately in English.",
    input="Three points can be used to illustrate what problems API aggregation services are suitable for solving.",
)

print(response.output_text)

output_text is suitable for reading standard text results. To handle function calls, search results, reasoning items, or other types, traverse response.output in order instead of keeping only message items. For the complete structure, see OpenAI Responses Reference.

Use Chat Completions

Chat Completions uses sequential messages. Ordinary text is usually located in the Assistant Message of the first Choice.

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "Please answer concisely and accurately in English.",
        },
        {
            "role": "user",
            "content": "Three points can be used to illustrate what problems API aggregation services are suitable for solving.",
        },
    ],
)

print(completion.choices[0].message.content)

If the model returns a tool call, message.content may be empty. Check message.tool_calls instead. See Chat Completions Reference for field definitions.

Receive streaming output

The OpenAI SDK exposes SSE responses as iterable event streams. Responses events have an explicit type. The following example prints only text deltas; production code should also handle completed, failed, and interrupted states.

stream = client.responses.create(
    model="MODEL_ID",
    input="Please introduce yourself in one sentence.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Status renewal (platform support required)

When the model, account, and upstream channel support response storage and continuation, the first round response can be saved and its ID used as the previous_response_id for the next request:

first = client.responses.create(
    model="MODEL_ID",
    store=True,
    input="Remember, the project code name is Aurora.",
)

second = client.responses.create(
    model="MODEL_ID",
    previous_response_id=first.id,
    input="What is the project code?",
)

print(second.output_text)

When using previous_response_id, the previous request's instructions do not automatically apply to the new request. Send any behavioral constraints that must remain in effect again.

If the current request path does not support response storage or continuation, maintain the history in your application and submit the required Input and Output Items in the next input. A complete history must preserve the message, reasoning, and tool-call relationships required by the application, not just plain text.

Timeouts, retries and errors

The OpenAI SDK converts HTTP errors into corresponding exception types and performs limited automatic retries for some connection errors, timeouts, rate limits, and server-side errors. Production applications should still explicitly set timeouts and retry limits based on request type to avoid long waits or repeated overlays.

Do not log the full API Key, request bodies containing sensitive data, or unprocessed user content in the logs. If the response provides a Request ID, it is recommended to save that identifier in the error log to facilitate locating the specific request.

Check completed

• The client Base URL is https://api.agtcloud.cn/v1, no duplicates /v1, and no specific endpoint path is appended.
• The API key is read from a trusted server environment and does not enter frontend code or version control.
• MODEL_ID has been replaced with the current API key, which is visible and supports the target entry model.
• Normal requests can correctly read text, status, and usage.
• Streaming code can distinguish text increments, completion events, and error events.
• Tool or multimodal requests are only sent to models that explicitly support the corresponding capabilities.

If an existing project needs to systematically replace the service provider configuration, please continue reading Provider SDK Migration; if you need to refactor the Chat structure into Responses, refer to Chat → Responses.