# pai-storage

Part of **PAI**

# Platform for AI (PAI) Storage

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Dynamic Mount Storage | Synchronous | Dynamically mount storage volumes to instances. |
| Configure Dynamic Mount | Synchronous | Configure dynamic mount points for instances. |

## API Calling Patterns

### Authentication
The primary authentication method is **Bearer Token** via the `Authorization` header.

- Use the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- Note: Some configuration endpoints (e.g., instance-level settings) may not require explicit authentication if managed through PAI instance metadata or role-based access, but API calls to PAI services should use the Bearer token method.

### Service Endpoint
PAI Storage APIs use region-specific endpoints following this pattern:

```text
https://pai-dsw.<region>.aliyuncs.com
```

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

Replace `<region>` with your target deployment region.

### Synchronous API Pattern
Both supported functions use a **Synchronous** calling pattern:

1. Send a POST or PUT request to the appropriate endpoint with JSON payload.
2. Include the `Authorization: Bearer <token>` header.
3. The server processes the request immediately and returns a response (typically `200 OK` on success).
4. No polling or async result retrieval is needed—response indicates final state.

This pattern is used for both enabling dynamic mounts and specifying mount point configurations.

## Parameter Reference

### Configure Dynamic Mount

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Enable | boolean | No | — | — | Specifies whether to enable dynamic mounting. |
| MountPoints | array | No | — | — | The list of dynamic mount targets. |

> Note: `MountPoints` typically contains objects describing storage buckets, mount paths, and access modes, though detailed sub-structure is defined in related PAI instance configuration schemas.

## Code Examples

### Configure Dynamic Mount - Python - cn-hangzhou

```python
import os
import requests

api_key = os.getenv("DASHSCOPE_API_KEY")
url = "https://pai-dsw.cn-hangzhou.aliyuncs.com/api/v1/instances/my-instance/dynamic-mount"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "Enable": True,
    "MountPoints": [
        {
            "BucketName": "my-pai-data-bucket",
            "MountPath": "/mnt/data",
            "ReadOnly": False
        }
    ]
}

response = requests.put(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())
```

### Dynamic Mount Storage - curl - cn-shanghai

```bash
curl -X POST \
  https://pai-dsw.cn-shanghai.aliyuncs.com/api/v1/storage/mount \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "InstanceId": "dsw-abc123",
    "StorageUri": "oss://my-bucket/path/to/data",
    "LocalPath": "/home/admin/data"
  }'
```

### Disable Dynamic Mount - Python - cn-beijing

```python
import os
import requests

url = "https://pai-dsw.cn-beijing.aliyuncs.com/api/v1/instances/dsw-xyz789/dynamic-mount"
headers = {"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}
data = {"Enable": False}

resp = requests.put(url, json=data, headers=headers)
if resp.status_code == 200:
    print("Dynamic mount disabled successfully.")
else:
    print("Failed:", resp.text)
```

### List Available Regions for PAI DSW

```text
PAI DSW (and thus Storage APIs) are available in the following regions:
- cn-hangzhou
- cn-shanghai
- cn-beijing
- cn-shenzhen
- ap-southeast-1
- cn-shanghai

Use the appropriate region in your endpoint URL.
```

## Error Handling

No specific error codes were extracted from the documentation. However, standard HTTP status codes apply:

- `401 Unauthorized`: Missing or invalid API key
- `403 Forbidden`: Insufficient permissions for the storage bucket or instance
- `404 Not Found`: Instance or storage resource does not exist
- `400 Bad Request`: Invalid JSON payload or missing required fields

Always check the response body for detailed error messages.

## Environment Requirements

- Set your API key: `export DASHSCOPE_API_KEY=your_api_key_here`
- Use any HTTP client capable of sending JSON payloads with custom headers (e.g., `requests` in Python, `OkHttp` in Java, `fetch` in Node.js)
- No specific SDK is required—these are standard REST APIs

## FAQ

Q: Do I need to pre-create the OSS bucket before mounting it?
A: Yes. The OSS bucket must exist and be accessible by the RAM role associated with your PAI instance or your API key’s permissions.

Q: Can I mount multiple storage buckets to the same instance?
A: Yes. The `MountPoints` array supports multiple entries, each pointing to a different bucket or path.

Q: Is dynamic mounting persistent across instance restarts?
A: It depends on your configuration. If you enable dynamic mounting via the instance configuration API (not just a one-time mount call), it can be made persistent. Check PAI instance lifecycle documentation for details.

Q: What happens if I try to mount to a path that already exists?
A: The behavior is undefined in the current docs—avoid conflicts by using unique or empty mount paths. Existing files in the mount path may be hidden.

Q: Are there size or performance limits on mounted storage?
A: Performance and capacity are governed by the underlying OSS bucket and instance type. There are no additional limits imposed by the dynamic mount feature itself.

## Pricing & Billing

### Billing Model
Dynamic Mount Storage operations are billed **per request**, regardless of success or failure. Configuration updates (e.g., toggling `Enable`) are free.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| default | ¥0.001 per call | ¥0.002 per call |

### Free Tier
1,000 free calls per month for Dynamic Mount Storage operations.

### Usage Limits
- Maximum 5 requests per second per project
- Applies only to the Dynamic Mount Storage API (not configuration)

### Billing Notes
Each API call to mount or manage dynamic storage is charged—even if the mount fails due to misconfiguration or permission errors. Configuration changes via the `Configure Dynamic Mount` endpoint are not billed.