cURL Access

Call CloudBase AI large models directly via HTTP API, suitable for backend services, scripts, and any programming language.

Prerequisites

1. Created a CloudBase environment (legacy plans can be upgraded), and enabled the model switch (see Overview)
2. Created an API Key (Get it here)

API Endpoint

https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/<PROVIDER>/chat/completions

Parameter	Description	Example
ENV_ID	Environment ID	your-env-id
PROVIDER	Model provider	cloudbase

Authentication

Add the API Key in the request header:

Authorization: Bearer <YOUR_API_KEY>

Text Generation

Non-streaming Call

curl -X POST 'https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase/chat/completions' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "hy3-preview",
    "messages": [
      {"role": "user", "content": "Tell me about Li Bai"}
    ],
    "stream": false
  }'

Response example:

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "hy3-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Li Bai (701-762), courtesy name Taibai, was a renowned Tang dynasty poet..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 150,
    "total_tokens": 160
  }
}

Streaming Call

curl -X POST 'https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase/chat/completions' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{
    "model": "hy3-preview",
    "messages": [
      {"role": "user", "content": "Introduce yourself"}
    ],
    "stream": true
  }'

Response format (SSE):

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"I"},"index":0}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":" am"},"index":0}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":" DeepSeek"},"index":0}]}

data: [DONE]

Request Parameters

Parameter	Type	Required	Description
model	string	Yes	Model name
messages	array	Yes	Message list
stream	boolean	No	Whether to stream response, defaults to false
temperature	number	No	Sampling temperature, range 0-2
top_p	number	No	Nucleus sampling, range 0-1
max_tokens	number	No	Maximum generated tokens

messages Format

[
  {"role": "system", "content": "You are a helpful assistant"},
  {"role": "user", "content": "User question"},
  {"role": "assistant", "content": "Assistant reply"},
  {"role": "user", "content": "Follow-up question"}
]

role	Description
system	System prompt, defines assistant behavior
user	User message
assistant	Assistant reply

Multi-turn Conversation

Multi-turn conversations require carrying the complete message history in each request. See the Multi-turn Conversation documentation for details.

Error Handling

Encountering errors during API calls? See Common Error Codes.

Programming Language Examples

Python

import requests

url = "https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase/chat/completions"
headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
}
data = {
    "model": "hy3-preview",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": False
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["choices"][0]["message"]["content"])

Node.js

const response = await fetch(
  "https://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <YOUR_API_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "hy3-preview",
      messages: [{ role: "user", content: "Hello" }]
    })
  }
);

const result = await response.json();
console.log(result.choices[0].message.content);