# pai-campaign

Part of **PAI**

# Platform for AI (PAI) Campaign Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Campaigns | Synchronous | Create, delete, get, list, and update campaigns. |

## 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`
- While some endpoints may not enforce authentication in documentation examples, production usage requires this header for all write and read operations (e.g., DeleteCampaign, GetCampaign). Always include it for reliability.

### Service Endpoint
APIs use region-specific base URLs:

- China regions: `https://api.aliyun.com/api/PaiPlugin/2022-01-12`
- International regions: `https://api.alibabacloud.com/api/PaiPlugin/2022-01-12`

Common regions include `cn-hangzhou`, `cn-shanghai`, and `ap-southeast-1`. Use the appropriate base URL based on your deployment region.

### Synchronous Request Pattern
All campaign management APIs follow a **Synchronous** pattern:
1. Send an HTTP request (GET, POST, PUT, or DELETE) to the specific endpoint.
2. Include required parameters in the path, query string, or request body.
3. Receive a complete JSON response immediately.
4. Parse the top-level `ErrorCode` field: `0` indicates success; any other value indicates an error.

No polling or streaming is involved—each call completes in one round trip.

## Parameter Reference

### Manage Campaigns

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Id | string | Conditional | — | — | Operational activity ID. Required for GetCampaign, UpdateCampaign, and DeleteCampaign. Obtain via ListCampaigns. |
| Name | string | No | — | — | Operational activity name. Used for filtering in ListCampaigns or setting during Create/Update. |
| Remark | string | No | — | — | Remarks for the campaign. Used for filtering or annotation. |
| PageNumber | integer | No | 1 | ≥ 1 | Page number for paginated results in ListCampaigns. |
| PageSize | integer | No | 10 | 1–100 | Number of campaigns per page in ListCampaigns. |
| body | object | No | — | — | Request payload container for CreateCampaign and UpdateCampaign (contains Name, Remark, etc.). |

## Code Examples

### Create a Campaign - JSON - All Regions

```json
{
  "Data": {
    "CreatedTime": "2020-01-01 12:00:00",
    "Id": "0a54e195-03e2-40bd-869d-b71cb302783e",
    "Name": "VIP客户",
    "Remark": "双十一活动",
    "UpdatedTime": "2020-01-01 12:00:00"
  },
  "ErrorCode": 0,
  "ErrorMessage": "OK",
  "RequestId": "f8651828-609d-4de8-ab49-ab781d7fd85a"
}
```

### Delete a Campaign - Bash - All Regions

```bash
curl -X DELETE https://api.aliyun.com/api/PaiPlugin/2022-01-12/DeleteCampaign/0bddaf8f-5628-427a-8652-5e24f6b4c35d \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"
```

### Get Campaign Details - Python - All Regions

```python
import requests

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

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

### List Campaigns with Filtering - JSON - All Regions

```json
{
  "Data": {
    "Campaigns": [
      {
        "CreatedTime": "2020-01-01 12:00:00",
        "Id": "0a54e195-03e2-40bd-869d-b71cb302783e",
        "Name": "VIP客户",
        "Remark": "双十一活动",
        "UpdatedTime": "2020-01-01 12:00:00"
      }
    ],
    "PageNumber": 1,
    "PageSize": 10,
    "TotalCount": 10
  },
  "ErrorCode": 0,
  "ErrorMessage": "OK",
  "RequestId": "f8651828-609d-4de8-ab49-ab781d7fd85a"
}
```

## Response Format

```json
{
  "Data": {
    "CreatedTime": "2020-01-01 12:00:00",
    "Id": "0a54e195-03e2-40bd-869d-b71cb302783e",
    "Name": "VIPcustomers",
    "Remark": "Double 11 campaign",
    "UpdatedTime": "2020-01-01 12:00:00"
  },
  "ErrorCode": 0,
  "ErrorMessage": "OK",
  "RequestId": "f8651828-609d-4de8-ab49-ab781d7fd85a"
}
```

**Key Fields**:
- `Data.Id` — Unique identifier of the campaign
- `Data.Name` — Name of the campaign
- `Data.Remark` — Optional descriptive remark
- `Data.CreatedTime` / `Data.UpdatedTime` — Timestamps in UTC+8 format
- `ErrorCode` — `0` for success; non-zero for errors
- `ErrorMessage` — Human-readable error description
- `RequestId` — Unique ID for tracing the request

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| 0 | Success. No error occurred. | Proceed normally. |
| 400 | Bad Request – The request parameters are invalid or missing. | Validate all required parameters and data formats. |
| 401 | Unauthorized – Authentication failed or API key is missing/expired. | Ensure `DASHSCOPE_API_KEY` is set and valid; include `Authorization: Bearer` header. |
| 403 | Forbidden – The user does not have permission to access this resource. | Verify your account has permissions for campaign management in PAI. |
| 404 | Not Found – The specified campaign ID does not exist. | Confirm the campaign ID exists by calling ListCampaigns first. |
| 500 | Internal Server Error – An unexpected error occurred on the server. | Retry with exponential backoff; contact support if persistent. |
| 503 | Service Unavailable – The service is temporarily unavailable due to overload or maintenance. | Wait and retry after a short delay. |

### Rate Limits & Retry
- **DeleteCampaign**: 100 QPS
- **GetCampaign**: Up to 10 requests per second
- **UpdateCampaign**: 100 QPS

Implement exponential backoff (e.g., 1s, 2s, 4s delays) on 429 or 5xx responses. Respect the `Retry-After` header if provided.

## Environment Requirements
- Set your API key: `export DASHSCOPE_API_KEY=your_key_here`
- For Python examples, install: `pip install requests`

## FAQ

Q: Do I need authentication for all campaign APIs?
A: Yes. While some documentation examples omit it, production endpoints require `Authorization: Bearer $DASHSCOPE_API_KEY` for all operations, including GET requests like GetCampaign and ListCampaigns.

Q: How do I obtain a campaign ID?
A: Call `ListCampaigns` to retrieve existing campaigns and their IDs. Use this ID for Get, Update, or Delete operations.

Q: What time zone is used for CreatedTime and UpdatedTime?
A: All timestamps are in **UTC+8** (China Standard Time), formatted as `YYYY-MM-DD HH:MM:SS`.

Q: Can I filter campaigns by both name and remark simultaneously?
A: Yes. Pass both `Name` and `Remark` as query parameters to `ListCampaigns` to apply combined filtering.

Q: Are campaign names unique?
A: The API does not enforce uniqueness of campaign names. Use the `Id` field as the definitive identifier.

## Pricing & Billing

### Billing Model
Billing is **per request**, regardless of success or failure.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| default | 0.001 / | 0.001 / |
| standard | 0.001 / | 0.001 / |

### Free Tier
- **DeleteCampaign**: 100 free calls per month
- **GetCampaign**: 1000 free requests per month
- **UpdateCampaign**: 100 free calls per month
- **ListCampaigns**: No free tier (but currently listed as 0 /)

### Usage Limits
- **DeleteCampaign**: 100 QPS
- **GetCampaign**: 10 requests per second
- **UpdateCampaign**: 100 QPS
- **ListCampaigns**: No explicit limit documented

### Billing Notes
- Each API call counts as one billable request, even if it fails.
- Minimum billing unit is 1 request.
- Pricing is in Chinese Yuan (CNY).