Conventions

This page describes the calling conventions shared by AGTCloud API endpoints. Refer to the relevant API Reference page for endpoint-specific fields, states, and response structures.

API address and Base URL

The API address used on this page is https://api.agtcloud.cn. OpenAI-compatible SDKs use https://api.agtcloud.cn/v1 as the Base URL.

Authentication

Most protected APIs use a Bearer API key:

Authorization: Bearer your-api-key

Anthropic Messages uses dedicated authentication headers and requires an API version:

x-api-key: your-api-key
anthropic-version: 2023-06-01

See the relevant endpoint page for optional headers such as anthropic-beta and authentication requirements for other protocols.

Go to API Keys to create and manage keys. Send only the API key in requests; do not use a console password, cookie, administrator token, or upstream provider key.

The following is a minimal Chat Completions request:

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

For guidance on creating, rotating, and securely storing API keys in production, see API keys, Base URL, and authentication.

Where request parameters go

Endpoint pages group parameters by their location in the request:

URL-encode path parameters before sending a request. Omit unused optional parameters instead of replacing every optional value with an empty string.

Content-Type and data formats

Do not hard-code the Multipart boundary. Let the browser, SDK, or HTTP client generate the complete Content-Type from the form data.

Model IDs

MODEL_ID in Reference examples is a placeholder. Replace it with a model ID available to the current API key. Use the model catalog to find models, or enter a key in Try It to retrieve the models available to that key.

Models, protocols, and upstream providers are separate concepts:

• The model ID selects the target model.
• The endpoint determines the protocol and message structure used by the client.
• A model may be available through multiple protocol endpoints or support only some fields.

Parse responses

Use the following order when handling a response:

Streaming responses

An SSE API sends multiple events or data chunks over one HTTP response. Read the content incrementally instead of waiting for the connection to close and parsing the entire response as one JSON object.

• Identify the end event or marker documented by the endpoint.
• Handle content deltas, tool calls, usage, and error events separately.
• If the network connection is interrupted, do not treat the content received so far as a complete result.
• Streaming event structures differ by protocol. Use the event definitions for the current endpoint.

Asynchronous tasks

Video, Midjourney, and similar APIs usually return a task identifier first, then provide progress and final results through a retrieval endpoint:

Submit task → save task ID → retrieve status → identify a terminal state → read the result

The field name for the task ID, status values, and retrieval path are protocol-specific. Do not mix id, task_id, video_id, or status values across APIs.

Use an interval and an overall timeout when polling, and stop after the task succeeds, fails, or is canceled. If a submission request times out but may have created a task, check its status before creating another billable task.

HTTP status and retries

The following are general handling guidelines. Refer to the actual endpoint response for its specific error structure.

Do not retry every error indefinitely. Parameter, authentication, and permission errors should be sent again only after correction. Before retrying a request with side effects, such as creating a task, determine whether it was already accepted.

For complete diagnostic steps, see Errors and troubleshooting.

Usage, time, and extension fields

• Whether usage data is present and how its fields are named depend on the protocol and model. Clients must allow it to be absent or null.
• Time fields may use Unix seconds, Unix milliseconds, or string timestamps. Parse them according to the endpoint schema.
• Provider extension fields usually apply only to some models and must not be treated as capabilities shared by all models.
• Response parsers should tolerate new non-critical fields so that compatible platform extensions do not break the entire response.

Security and logging

• Store long-lived API keys in a trusted server or secret manager. Never embed them in production web, desktop, or mobile clients.
• Documentation Try It is only for temporary browser testing initiated by the user. Do not use a long-lived production key on a shared device.
• Never place a key in a public repository, screenshot, log, or support ticket.
• Redact prompts, file URLs, account data, and sensitive request or response content from troubleshooting materials.
• Disable or delete keys that are no longer used or may have been exposed, then update every service that uses them.

Continue reading: API Reference · Quickstart · Errors and troubleshooting