Initial commit
This commit is contained in:
Zhongwei Li
734
references/api-reference.md
Normal file
734
references/api-reference.md
Normal file
@@ -0,0 +1,734 @@
|
||||
# SAP AI Core API Reference
|
||||
|
||||
Complete API reference for SAP AI Core.
|
||||
|
||||
**Documentation Source:** [https://github.com/SAP-docs/sap-artificial-intelligence/tree/main/docs/sap-ai-core](https://github.com/SAP-docs/sap-artificial-intelligence/tree/main/docs/sap-ai-core)
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
### OAuth Token Endpoint
|
||||
|
||||
```bash
|
||||
curl -X POST "[https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token"](https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token") \
|
||||
-H "Content-Type: application/x-www-form-urlencoded" \
|
||||
-d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET"
|
||||
```
|
||||
|
||||
### Required Headers
|
||||
|
||||
| Header | Description |
|
||||
|--------|-------------|
|
||||
| `Authorization` | `Bearer <token>` |
|
||||
| `AI-Resource-Group` | Resource group name (e.g., `default`) |
|
||||
| `Content-Type` | `application/json` |
|
||||
|
||||
---
|
||||
|
||||
## Base URLs
|
||||
|
||||
| Environment | URL Pattern |
|
||||
|-------------|-------------|
|
||||
| AI API | `[https://api.ai.prod.<region>.hana.ondemand.com`](https://api.ai.prod.<region>.hana.ondemand.com`) |
|
||||
| Inference | `[https://api.ai.prod.<region>.hana.ondemand.com/v2/inference/deployments/<deployment-id>`](https://api.ai.prod.<region>.hana.ondemand.com/v2/inference/deployments/<deployment-id>`) |
|
||||
| OAuth | `[https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token`](https://<id-zone>.authentication.<region>.hana.ondemand.com/oauth/token`) |
|
||||
|
||||
**Regions:** `eu10`, `eu11`, `us10`, `us21`, `jp10`, `ap10`, `ap11`
|
||||
|
||||
---
|
||||
|
||||
## API Versioning
|
||||
|
||||
All endpoints use the `/v2/*` versioned routes:
|
||||
- `/v2/lm/*` - Language model operations
|
||||
- `/v2/inference/*` - Inference deployments
|
||||
- `/v2/admin/*` - Administrative operations (secrets, repositories)
|
||||
|
||||
---
|
||||
|
||||
## Scenarios
|
||||
|
||||
### List Scenarios
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/scenarios
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"count": 2,
|
||||
"resources": [
|
||||
{
|
||||
"id": "foundation-models",
|
||||
"name": "Foundation Models",
|
||||
"description": "Access to generative AI models"
|
||||
},
|
||||
{
|
||||
"id": "orchestration",
|
||||
"name": "Orchestration",
|
||||
"description": "Unified model access with pipeline features"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Models
|
||||
|
||||
### List Available Models
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/scenarios/foundation-models/models
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"count": 50,
|
||||
"resources": [
|
||||
{
|
||||
"model": "gpt-4o",
|
||||
"accessType": "Remote",
|
||||
"displayName": "GPT-4o",
|
||||
"provider": "azure-openai",
|
||||
"executableId": "azure-openai",
|
||||
"versions": [
|
||||
{
|
||||
"name": "2024-05-13",
|
||||
"isLatest": true,
|
||||
"capabilities": ["text-generation", "chat"],
|
||||
"contextLength": 128000,
|
||||
"inputCost": 5.0,
|
||||
"outputCost": 15.0,
|
||||
"isStreamingSupported": true
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configurations
|
||||
|
||||
### Create Configuration
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/lm/configurations
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "my-config",
|
||||
"executableId": "azure-openai",
|
||||
"scenarioId": "foundation-models",
|
||||
"parameterBindings": [
|
||||
{"key": "modelName", "value": "gpt-4o"},
|
||||
{"key": "modelVersion", "value": "latest"}
|
||||
],
|
||||
"inputArtifactBindings": []
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "abc123-def456-ghi789",
|
||||
"message": "Configuration created"
|
||||
}
|
||||
```
|
||||
|
||||
### List Configurations
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/configurations
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `scenarioId` | Filter by scenario |
|
||||
| `executableId` | Filter by executable |
|
||||
| `$top` | Limit results |
|
||||
| `$skip` | Skip results |
|
||||
|
||||
### Get Configuration
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/configurations/{configurationId}
|
||||
```
|
||||
|
||||
### Delete Configuration
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/lm/configurations/{configurationId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployments
|
||||
|
||||
### Create Deployment
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/lm/deployments
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"configurationId": "<configuration-id>",
|
||||
"ttl": "24h"
|
||||
}
|
||||
```
|
||||
|
||||
**TTL Format:** Natural numbers with units: `m` (minutes), `h` (hours), `d` (days)
|
||||
- Valid: `5m`, `2h`, `7d`
|
||||
- Invalid: `4.5h`, `4h30m` (fractional and combined units not supported)
|
||||
- **Tip:** Convert combined durations to a single unit (e.g., `270m` instead of `4h30m`)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "d12345-abcd-efgh",
|
||||
"deploymentUrl": "[https://...",](https://...",)
|
||||
"status": "PENDING",
|
||||
"message": "Deployment created"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Deployment
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/deployments/{deploymentId}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "d12345-abcd-efgh",
|
||||
"configurationId": "c12345-abcd",
|
||||
"configurationName": "my-config",
|
||||
"scenarioId": "foundation-models",
|
||||
"status": "RUNNING",
|
||||
"statusMessage": "",
|
||||
"deploymentUrl": "[https://...",](https://...",)
|
||||
"createdAt": "2024-01-15T10:00:00Z",
|
||||
"modifiedAt": "2024-01-15T10:05:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Deployment Statuses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `UNKNOWN` | Initial state |
|
||||
| `PENDING` | Starting up |
|
||||
| `RUNNING` | Active, serving requests |
|
||||
| `STOPPING` | Shutting down |
|
||||
| `STOPPED` | Inactive |
|
||||
| `DEAD` | Failed |
|
||||
|
||||
### List Deployments
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/deployments
|
||||
```
|
||||
|
||||
### Update Deployment
|
||||
|
||||
```bash
|
||||
PATCH $AI_API_URL/v2/lm/deployments/{deploymentId}
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"configurationId": "<new-configuration-id>"
|
||||
}
|
||||
```
|
||||
|
||||
### Stop Deployment
|
||||
|
||||
```bash
|
||||
PATCH $AI_API_URL/v2/lm/deployments/{deploymentId}
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"targetStatus": "STOPPED"
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Deployment
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/lm/deployments/{deploymentId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Executions
|
||||
|
||||
### Create Execution
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/lm/executions
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"configurationId": "<configuration-id>"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Execution
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/executions/{executionId}
|
||||
```
|
||||
|
||||
### Execution Statuses
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `UNKNOWN` | Initial state |
|
||||
| `PENDING` | Queued |
|
||||
| `RUNNING` | Executing |
|
||||
| `COMPLETED` | Finished successfully |
|
||||
| `DEAD` | Failed |
|
||||
| `STOPPED` | Manually stopped |
|
||||
|
||||
### List Executions
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/executions
|
||||
```
|
||||
|
||||
### Stop Execution
|
||||
|
||||
```bash
|
||||
PATCH $AI_API_URL/v2/lm/executions/{executionId}
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"targetStatus": "STOPPED"
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Execution
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/lm/executions/{executionId}
|
||||
```
|
||||
|
||||
### Get Execution Logs
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/executions/{executionId}/logs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Artifacts
|
||||
|
||||
### Register Artifact
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/lm/artifacts
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "training-data",
|
||||
"kind": "dataset",
|
||||
"url": "ai://<object-store>/<path>",
|
||||
"scenarioId": "<scenario-id>",
|
||||
"description": "Training dataset"
|
||||
}
|
||||
```
|
||||
|
||||
**Artifact Kinds:**
|
||||
- `dataset`: Training data
|
||||
- `model`: Trained model
|
||||
- `resultset`: Inference results
|
||||
- `other`: Other artifacts
|
||||
|
||||
### Get Artifact
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/artifacts/{artifactId}
|
||||
```
|
||||
|
||||
### List Artifacts
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/artifacts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resource Groups
|
||||
|
||||
### Create Resource Group
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/admin/resourceGroups
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"resourceGroupId": "my-resource-group"
|
||||
}
|
||||
```
|
||||
|
||||
### List Resource Groups
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/admin/resourceGroups
|
||||
```
|
||||
|
||||
### Delete Resource Group
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/admin/resourceGroups/{resourceGroupId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Secrets
|
||||
|
||||
### Create Generic Secret
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/admin/secrets
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "my-secret",
|
||||
"data": {
|
||||
"key1": "value1",
|
||||
"key2": "value2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Create Object Store Secret
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/admin/objectStoreSecrets
|
||||
```
|
||||
|
||||
**AWS S3:**
|
||||
```json
|
||||
{
|
||||
"name": "default",
|
||||
"type": "S3",
|
||||
"pathPrefix": "my-bucket/path",
|
||||
"data": {
|
||||
"AWS_ACCESS_KEY_ID": "<key>",
|
||||
"AWS_SECRET_ACCESS_KEY": "<secret>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List Secrets
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/admin/secrets
|
||||
```
|
||||
|
||||
### Delete Secret
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/admin/secrets/{secretName}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Meta API
|
||||
|
||||
### Get Runtime Capabilities
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/lm/meta
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"logs.executions": true,
|
||||
"logs.deployments": true,
|
||||
"multitenant": true,
|
||||
"shareable": false,
|
||||
"staticDeployments": true,
|
||||
"userDeployments": true,
|
||||
"userExecutions": true,
|
||||
"timeToLiveDeployments": true,
|
||||
"analytics": true,
|
||||
"bulkUpdates": true,
|
||||
"executionSchedules": true
|
||||
},
|
||||
"limits": {
|
||||
"deployments.maxRunningCount": 10,
|
||||
"executions.maxRunningCount": 10,
|
||||
"minimumFrequencyHour": 1,
|
||||
"timeToLiveDeployments.minimum": "5m",
|
||||
"timeToLiveDeployments.maximum": "90d"
|
||||
},
|
||||
"extensions": {
|
||||
"analytics": "1.0",
|
||||
"metrics": "1.0",
|
||||
"resourceGroups": "1.0",
|
||||
"dataset": "1.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Orchestration API
|
||||
|
||||
### Chat Completion
|
||||
|
||||
```bash
|
||||
POST $ORCHESTRATION_URL/v2/completion
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"module_configurations": {
|
||||
"llm_module_config": {
|
||||
"model_name": "gpt-4o",
|
||||
"model_version": "latest",
|
||||
"model_params": {
|
||||
"max_tokens": 1000,
|
||||
"temperature": 0.7
|
||||
}
|
||||
},
|
||||
"templating_module_config": {
|
||||
"template": [
|
||||
{"role": "system", "content": "{{?system}}"},
|
||||
{"role": "user", "content": "{{?user}}"}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"input_params": {
|
||||
"system": "You are a helpful assistant.",
|
||||
"user": "Hello!"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Streaming Completion
|
||||
|
||||
```bash
|
||||
POST $ORCHESTRATION_URL/v2/completion
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"module_configurations": {
|
||||
"llm_module_config": {
|
||||
"model_name": "gpt-4o",
|
||||
"model_version": "latest",
|
||||
"model_params": {
|
||||
"stream": true
|
||||
}
|
||||
},
|
||||
"templating_module_config": {
|
||||
"template": [{"role": "user", "content": "{{?prompt}}"}]
|
||||
}
|
||||
}
|
||||
},
|
||||
"input_params": {"prompt": "Tell me a story"}
|
||||
}
|
||||
```
|
||||
|
||||
### Embeddings
|
||||
|
||||
```bash
|
||||
POST $ORCHESTRATION_URL/v2/embeddings
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"module_configurations": {
|
||||
"embedding_module_config": {
|
||||
"model_name": "text-embedding-3-large",
|
||||
"model_version": "latest",
|
||||
"model_params": {
|
||||
"encoding_format": "float",
|
||||
"dimensions": 1024
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"input": ["Text to embed"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Grounding API
|
||||
|
||||
### Create Pipeline
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/lm/groundingPipelines
|
||||
```
|
||||
|
||||
**Request Body (SharePoint):**
|
||||
```json
|
||||
{
|
||||
"name": "hr-docs-pipeline",
|
||||
"configuration": {
|
||||
"dataSource": {
|
||||
"type": "sharepoint",
|
||||
"configuration": {
|
||||
"siteUrl": "[https://company.sharepoint.com/sites/HR",](https://company.sharepoint.com/sites/HR",)
|
||||
"folderPath": "/Documents/Policies"
|
||||
}
|
||||
},
|
||||
"secretName": "sharepoint-secret"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List Pipelines
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/groundingPipelines
|
||||
```
|
||||
|
||||
### Delete Pipeline
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/lm/groundingPipelines/{pipelineId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
### Standard Error Format
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human-readable error message",
|
||||
"requestId": "req-12345",
|
||||
"target": "deployments"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
| Code | HTTP Status | Description |
|
||||
|------|-------------|-------------|
|
||||
| `UNAUTHORIZED` | 401 | Invalid or expired token |
|
||||
| `FORBIDDEN` | 403 | Missing permissions or quota exceeded |
|
||||
| `NOT_FOUND` | 404 | Resource not found |
|
||||
| `CONFLICT` | 409 | Resource already exists |
|
||||
| `QUOTA_EXCEEDED` | 429 | Rate limit or quota exceeded |
|
||||
| `INTERNAL_ERROR` | 500 | Server error |
|
||||
|
||||
---
|
||||
|
||||
## Bulk Operations
|
||||
|
||||
### Bulk Update Deployments
|
||||
|
||||
```bash
|
||||
PATCH $AI_API_URL/v2/lm/deployments
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"deployments": [
|
||||
{"id": "dep1", "targetStatus": "STOPPED"},
|
||||
{"id": "dep2", "targetStatus": "STOPPED"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Limit:** 100 items per request
|
||||
|
||||
### Bulk Delete Deployments
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/lm/deployments
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"deploymentIds": ["dep1", "dep2", "dep3"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Schedules
|
||||
|
||||
### Create Schedule
|
||||
|
||||
```bash
|
||||
POST $AI_API_URL/v2/lm/executionSchedules
|
||||
```
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"configurationId": "<config-id>",
|
||||
"cron": "0 0 * * *",
|
||||
"start": "2024-01-01T00:00:00Z",
|
||||
"end": "2024-12-31T23:59:59Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Cron Format:** `minute hour day month weekday`
|
||||
|
||||
### List Schedules
|
||||
|
||||
```bash
|
||||
GET $AI_API_URL/v2/lm/executionSchedules
|
||||
```
|
||||
|
||||
### Delete Schedule
|
||||
|
||||
```bash
|
||||
DELETE $AI_API_URL/v2/lm/executionSchedules/{scheduleId}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation Links
|
||||
|
||||
- AI API Overview: [https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/ai-api-overview-716d4c3.md](https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/ai-api-overview-716d4c3.md)
|
||||
- Configurations: [https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/create-configurations-884ae34.md](https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/create-configurations-884ae34.md)
|
||||
- Deployments: [https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/deploy-models-dd16e8e.md](https://github.com/SAP-docs/sap-artificial-intelligence/blob/main/docs/sap-ai-core/deploy-models-dd16e8e.md)
|
||||
Reference in New Issue
Block a user