# Overview

predictor.sh exposes OpenAI-compatible and ElevenLabs-compatible APIs, allowing you to use existing SDKs and tools.

## Base URL

Your endpoint URL is displayed when you start predictor:

```
https://abc123.predictor.sh
```

All API endpoints are relative to this base URL.

## Authentication

All requests require a Bearer token in the Authorization header:

```bash
curl https://abc123.predictor.sh/v1/chat/completions \
  -H "Authorization: Bearer pred_your_token"
```

## Available Endpoints

### Text Generation

| Endpoint               | Method | Description      |
| ---------------------- | ------ | ---------------- |
| `/v1/chat/completions` | POST   | Chat completions |
| `/v1/completions`      | POST   | Text completions |
| `/v1/embeddings`       | POST   | Text embeddings  |
| `/v1/models`           | GET    | List models      |
| `/health`              | GET    | Health check     |

### Speech-to-Text

| Endpoint                   | Method | Description      |
| -------------------------- | ------ | ---------------- |
| `/v1/audio/transcriptions` | POST   | Transcribe audio |

### Text-to-Speech

| Endpoint                               | Method | Description                  |
| -------------------------------------- | ------ | ---------------------------- |
| `/v1/audio/speech`                     | POST   | Generate speech (OpenAI)     |
| `/v1/text-to-speech/{voice_id}`        | POST   | Generate speech (ElevenLabs) |
| `/v1/text-to-speech/{voice_id}/stream` | POST   | Streaming speech             |
| `/v1/voices`                           | GET    | List voices                  |

## SDK Compatibility

### OpenAI Python SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://abc123.predictor.sh/v1",
    api_key="pred_your_token"
)

# Chat completions
response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Audio transcription
transcript = client.audio.transcriptions.create(
    model="whisper-1",
    file=open("audio.mp3", "rb")
)

# Text to speech
speech = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="Hello world"
)
```

### OpenAI JavaScript SDK

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://abc123.predictor.sh/v1',
  apiKey: 'pred_your_token',
});

const response = await client.chat.completions.create({
  model: 'default',
  messages: [{ role: 'user', content: 'Hello!' }],
});
```

### curl

```bash
curl https://abc123.predictor.sh/v1/chat/completions \
  -H "Authorization: Bearer pred_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Error Responses

Errors follow the OpenAI error format:

```json
{
  "error": {
    "message": "Invalid request: missing 'messages' field",
    "type": "invalid_request_error",
    "code": "missing_field"
  }
}
```

### HTTP Status Codes

| Code | Description                          |
| ---- | ------------------------------------ |
| 200  | Success                              |
| 400  | Bad request (invalid parameters)     |
| 401  | Unauthorized (invalid/missing token) |
| 403  | Forbidden (IP not allowed)           |
| 429  | Too many requests                    |
| 500  | Server error                         |
| 502  | Tunnel connection lost               |
| 503  | Endpoint offline                     |
| 504  | Request timeout                      |
