# pai-api-catalog

Part of **PAI**

# Platform for AI (PAI) API & Service Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Access AI Service Endpoints | Synchronous | Browse the catalog of available AI service endpoints. |
| Discover Available APIs | Synchronous | Browse the catalog of available PAI APIs. |
| Access PAAI Service Endpoints | Synchronous | Connect to general PAI service endpoints. |
| Access API | Synchronous | Reference for general platform API operations. |
| Call Model Service API | Synchronous | Access the list of operations for calling model service APIs. |
| List Connections | Synchronous | Retrieve a list of configured connections. |
| List Gateway Domains | Synchronous | List custom domains attached to gateways. |
| Manage Message Configuration | Synchronous | Retrieve message service configuration. |

## API Calling Patterns

### Authentication
The primary authentication method is **Bearer Token**.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY` (or `PAI_API_KEY` for some services)
- Some services also support AccessKey ID/Secret via SDK configuration, but Bearer Token is recommended for consistency across PAI APIs.

### Service Endpoint (Endpoint)
PAI APIs use region-specific endpoints with the following patterns:

- China regions: `https://api.aliyun.com/api/{service}/{version}/{operation}`
- International regions: `https://api.alibabacloud.com/api/{service}/{version}/{operation}`

Common regions include:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

For general PAI service endpoints (e.g., PAI Rec Service), use:
- Public: `pairecservice.{region}.aliyuncs.com`
- VPC: `pairecservice-vpc.{region}.aliyuncs.com`

### Synchronous API Pattern
All functions in this domain use the **Synchronous** calling pattern:

1. Send an HTTP request (GET or POST) to the appropriate endpoint with required parameters.
2. Include the `Authorization: Bearer <your_api_key>` header.
3. Receive a complete JSON response immediately.
4. Parse the response body for results or error information.

No polling or streaming is required—each call returns the full result in one response.

## Parameter Reference

### List Connections

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | false | — | — | Workspace ID. You can call ListWorkspaces to obtain the workspace ID. |
| NextToken | string | false | — | — | The token that marks the starting position for the next page of results. |
| MaxResults | integer | false | — | — | Maximum number of entries per page. |
| SortBy | string | false | GmtCreateTime | Valid values: GmtCreateTime | Field by which to sort results. |
| Order | string | false | DESC | Valid values: ASC, DESC | Sort order. |
| ConnectionIds | array | false | — | — | List of connection IDs to filter by. |
| ConnectionName | string | false | — | — | Connection name. Supports fuzzy matching. |
| ConnectionTypes | array | false | — | Valid values: DashScopeConnection, OpenLLMConnection, MilvusConnection, OpenSearchConnection, LindormConnection, ElasticsearchConnection, HologresConnection, RDSConnection, CustomConnection | List of connection types to filter by. |
| EncryptOption | string | false | — | Valid values: PlainText, Secret | Encryption option for sensitive fields in the response. |
| Model | string | false | — | — | Model identifier. Filters connections associated with this model. |
| ModelTypes | array | false | — | Valid values: LLM, Embedding, ReRank | List of model types to filter by. |
| ToolCall | boolean | false | — | Valid values: true, false | Whether tool calling is supported. |
| Creator | string | false | — | — | Alibaba Cloud account ID of the creator. |
| Accessibility | string | false | — | Valid values: PUBLIC, PRIVATE | Visibility of the connection. |

### List Gateway Domains

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| ClusterId | string | true | — | — | The region where the private gateway is located. |
| GatewayId | string | true | — | — | The ID of the private gateway. |

## Code Examples

### List Connections - curl - all

```bash
curl -X GET 'https://api.aliyun.com/api/AIWorkSpace/2021-02-04/ListConnections?WorkspaceId=478**&MaxResults=10&SortBy=GmtCreateTime&Order=DESC' \
-H 'Authorization: Bearer <your-api-key>' \
-H 'Content-Type: application/json'
```

### GetMessageConfig - bash - all

```bash
curl -X GET \
  'https://api.aliyun.com/api/PaiPlugin/2022-01-12/GetMessageConfig' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json'
```

### GetMessageConfig - Python - all

```python
import requests

url = "https://api.aliyun.com/api/PaiPlugin/2022-01-12/GetMessageConfig"
headers = {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())
```

### Call Model Service API - Python - all

```python
import pai_rec_service
# Example usage with SDK
client = pai_rec_service.Client(access_key_id='your-access-key-id',
                               access_key_secret='your-access-key-secret',
                               endpoint='https://api.pai-recservice.com')
response = client.call_api(operation='GetRecommendations', params={'user_id': '12345'})
print(response)
```

### ListGatewayDomains - curl - all

```bash
curl -X GET 'https://api.aliyun.com/api/eas/2021-07-01/ListGatewayDomains?ClusterId=cn-shanghai&GatewayId=gw-1uhcqmsc7x22******' \ 
-H 'Authorization: Bearer $DASHSCOPE_API_KEY' \ 
-H 'Content-Type: application/json'
```

## Response Format

```json
{
  "Connections": [
    {
      "Description": "This is a description of a database connection.",
      "ConnectionType": "ElasticsearchConnection",
      "Accessibility": "PRIVATE",
      "Secrets": {
        "key": "Dsjk***hsl01\n"
      },
      "WorkspaceId": "228**",
      "Creator": "20925961****557803",
      "ResourceMeta": {
        "InstanceName": "lindorm-xxxxxxx",
        "Extra": "{\"vpcId\":\"vpc-xxxx\"}",
        "InstanceId": "ld-2vc1***v1zaqgzol"
      },
      "GmtModifiedTime": "2025-03-07T07:54:56Z\n",
      "ConnectionName": "lindorm-connection",
      "ConnectionId": "conn-pai9m***mi47",
      "Configs": {
        "key": "12345"
      },
      "Models": [
        {
          "ToolCall": true,
          "Model": "model_001",
          "DisplayName": "BGE model deploy.",
          "ModelType": "LLM"
        }
      ],
      "GmtCreateTime": "2025-03-07T07:54:56Z\n"
    }
  ],
  "MaxResults": 10,
  "NextToken": "15",
  "TotalCount": 27,
  "RequestId": "B2C51F93-1C07-5477-9705-5FDB****F19F"
}
```

**Key Fields**:
- `Connections` — Array of connection objects with metadata and configuration
- `MaxResults` — Maximum number of results returned in this page
- `NextToken` — Token for fetching the next page of results
- `TotalCount` — Total number of connections matching the query
- `RequestId` — Unique identifier for the API request (useful for support)

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| 400 | Bad Request. The request parameters are invalid or missing. | Validate all required parameters and their formats. |
| 401 | Unauthorized - Authentication failed. Check your API key or credentials. | Ensure your API key is valid and correctly formatted in the Authorization header. |
| 403 | Forbidden. The user does not have sufficient permissions to access the requested resource. | Verify your account has the necessary RAM permissions for the requested operation. |
| 404 | Not Found. The specified workspace or connection does not exist. | Confirm the WorkspaceId, ConnectionId, or other resource identifiers are correct. |
| 500 | Internal Server Error. An unexpected error occurred on the server side. | Retry the request after a short delay; contact support if the issue persists. |
| 503 | Service Unavailable. The service is temporarily unavailable due to overload or maintenance. | Implement exponential backoff and retry logic. |
| InvalidParameter.ClusterId | The specified ClusterId is invalid or does not exist. | Use a valid region ID (e.g., cn-hangzhou, cn-shanghai). |
| InvalidParameter.GatewayId | The specified GatewayId is invalid or does not exist. | Obtain the correct GatewayId from the ListGateway API response. |
| ResourceNotFound | The requested private gateway or its configuration could not be found. | Ensure the gateway exists in the specified cluster and you have access to it. |
| UnauthorizedOperation | The caller does not have sufficient permissions to access the private gateway. | Assign appropriate RAM policies to your user or role. |

## Pricing & Billing

### Billing Model
All APIs in this domain use **per-request** billing.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| standard | 0.0001 / | 0.0001 / |
| default | 0.001 / | 0.001 / |
| default | 0.001 / | 0.002 / |
| default | 0.002 /tokens | 0.004 /tokens |

### Free Tier
- 10,000 free API calls per month (API catalog)
- 500 free requests per month (API discovery)
- 100 tokens (PAI service endpoints)
- 1000 (most other operations)

### Usage Limits
- 100 QPS per user/account (varies by service)
- 8K tokens (for token-based services)
- 10 (List Connections)

### Billing Notes
- API usage is billed per request; free tier resets monthly on the 1st.
- Billing starts after the free tier is exhausted. Usage is tracked per API call.
- token (for token-based services).
- Each successful request is billed once. Free tier resets monthly.

## FAQ

Q: How do I authenticate my API requests to PAI services?
A: Use the `Authorization: Bearer <your_api_key>` header. Set your API key in the `DASHSCOPE_API_KEY` environment variable for convenience.

Q: What regions are supported for PAI APIs?
A: Common regions include `cn-hangzhou`, `cn-shanghai`, `cn-beijing`, `ap-southeast-1`, `eu-central-1`, and `cn-hangzhou`. Use `api.aliyun.com` for China regions and `api.alibabacloud.com` for international regions.

Q: Why am I getting a 403 Forbidden error?
A: Your account likely lacks the necessary RAM permissions. Ensure your RAM user has policies granting access to the specific PAI operations you're trying to perform.

Q: How do I handle pagination in list operations like ListConnections?
A: Use the `NextToken` from the response to fetch subsequent pages. Include it as a parameter in your next request until `NextToken` is no longer returned.

Q: Are there any free usage quotas?
A: Yes—most operations include a free tier (typically 500–10,000 requests per month). Token-based services offer up to 1 million free tokens monthly.