> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tramlabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tramlabs.io/_mcp/server.

# Tổng quan

> Tổng quan API của Trạm AI

Trạm AI cung cấp API tương thích OpenAI, cho phép bạn dùng các thư viện OpenAI SDK có sẵn hoặc gọi HTTP trực tiếp.

## Base URL

```
https://api.tramlabs.io/v1
```

## Endpoints

| Endpoint                   | Method | Mô tả                                               |
| -------------------------- | ------ | --------------------------------------------------- |
| `/v1/chat/completions`     | POST   | Chat completion (OpenAI-compatible)                 |
| `/v1/completions`          | POST   | Text completion (**legacy** — chưa có model hỗ trợ) |
| `/v1/embeddings`           | POST   | Tạo embeddings                                      |
| `/v1/messages`             | POST   | Anthropic Messages API                              |
| `/v1/responses`            | POST   | OpenAI Responses API                                |
| `/v1/images/generations`   | POST   | Tạo ảnh từ text                                     |
| `/v1/images/edits`         | POST   | Chỉnh sửa ảnh                                       |
| `/v1/audio/speech`         | POST   | Text-to-Speech                                      |
| `/v1/audio/transcriptions` | POST   | Speech-to-Text                                      |
| `/v1/rerank`               | POST   | Rerank documents                                    |
| `/v1/videos`               | POST   | Tạo video (async)                                   |
| `/v1/videos/{id}`          | GET    | Xem trạng thái video job                            |
| `/v1/videos`               | GET    | Liệt kê video jobs                                  |
| `/v1/videos/{id}/content`  | GET    | Tải video đã hoàn tất                               |
| `/v1/models`               | GET    | Liệt kê models                                      |
| `/public/models`           | GET    | Public model catalog (không cần auth)               |
| `/public/models/{model}`   | GET    | Chi tiết public model                               |
| `/public/models/rankings`  | GET    | Bảng xếp hạng models                                |

## Model Name

Tất cả các endpoint inference đều yêu cầu parameter `model`. Giá trị này là **slug** của model trên Trạm AI (ví dụ: `gemini-3.5-flash`), không phải tên nội bộ của provider.

Có 2 cách lấy tên model:

| Nguồn                                                       | Trường               | Auth        | Ví dụ                |
| ----------------------------------------------------------- | -------------------- | ----------- | -------------------- |
| [`GET /v1/models`](/api/endpoints/models)                   | `data[].id`          | Cần API key | `"gemini-3.5-flash"` |
| [`GET /public/models`](/api/endpoints/models#public-models) | `models[].modelName` | Không cần   | `"gemini-3.5-flash"` |

Hoặc duyệt trực tiếp trên [trang Models](https://tramlabs.io/models).

```bash
# Lấy danh sách model (cần auth)
curl https://api.tramlabs.io/v1/models \
  -H "Authorization: Bearer $TRAM_AI_API_KEY"

# Lấy danh sách model (không cần auth)
curl https://api.tramlabs.io/public/models
```

## Response Format

Tất cả endpoint trả về JSON theo chuẩn OpenAI, ví dụ:

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}
```