Updated on 2025-07-01 GMT+08:00

Making an API Request

This section describes the structure of a REST API, and uses the API for obtaining a user token as an example to demonstrate how to call an API.

A request consists of the request URI, request method, request header, and request body.

Request URI

A request URI is in the following format:

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

Table 1 Request URI

Parameter

Description

URI-scheme

Protocol used to transmit requests. All APIs use HTTPS.

Endpoint

Domain name or IP address of the server bearing the REST service.

resource-path

Access path of an API for performing a specified operation. You can obtain the path from the URI of a specific API.

query-string

Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of "Parameter name=Parameter value".

For details about how to obtain the request URI, see Request URI. The following is an example:

https://{endpoint}/v1/{project_id}/deployments/{deployment_id}/chat/completions

Request Methods

HTTP request method, which indicates the type of operation that the service is requesting. The options are as follows:

  • GET: requests the server to return specified resources.
  • PUT: requests the server to update specified resources.
  • POST: requests the server to add resources or perform special operations.
  • DELETE: requests the server to delete specified resources, for example, an object.
  • HEAD: same as GET except that the server must return only the response header.
  • PATCH: requests the server to update partial content of a specified resource. If the resource does not exist, a new resource will be created.

The request method in the URI of the API is POST, for example:

POST https://{endpoint}/v1/{project_id}/deployments/{deployment_id}/chat/completions

Request Header

You can also add additional header fields to a request, such as the fields required by a specified URI or HTTP method. For example, to request for the authentication information, add Content-Type, which specifies the request body type.

Common request headers are as follows:

  • Content-Type: specifies the request body type or format. This field is mandatory and its default value is application/json.
  • X-Auth-Token: specifies a user token only for token-based API authentication. For details about user tokens, see Token-based Authentication in Authentication.

    In addition to supporting token-based authentication, APIs also support authentication using access key ID/secret access key (AK/SK). During AK/SK-based authentication, an SDK is used to sign the request, and the Authorization (signature information) and X-Sdk-Date (time when the request is sent) header fields are automatically added to the request. For more details, see Authentication.

The following provides an example request with a header included.

POST https://{endpoint}/v1/{project_id}/deployments/{deployment_id}/chat/completions
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINOD... 

Request Body

The body of a request is often sent in a structured format as specified in the Content-Type header field. The request body transfers content except the request header. If the request body contains Chinese characters, these characters must be coded in UTF-8.

The request body varies between APIs. Some APIs do not require the request body, such as the APIs requested using the GET and DELETE methods.

The following provides an example request with a body included. For details about the parameters, see the specific API.
POST https://{endpoint}/v1/{project_id}/deployments/{deployment_id}/chat/completions
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINOD... 
{
    "messages": [
      {
          "content": "Introduce the Yangtze River and its typical fish species."
       }
      ],
    "temperature": 0.9,
    "max_tokens": 600
}

You can send the request to call an API through curl, Postman, or coding. For an API, you can obtain the request parameters and parameter descriptions in the response.