# Streamlet — Video & Image Infrastructure for Developers

> Streamlet is a video and image infrastructure API for developers. Upload once, stream globally with HLS encoding, automatic captions, WebP image hosting, thumbnail generation, and real-time analytics — zero egress fees.

## What is Streamlet?

Streamlet provides two primary interfaces:
- **REST API** — language-agnostic HTTP endpoints for backend integration
- **NPM SDK** (`@streamlet/sdk`) — JavaScript/TypeScript client with a React player component

**Website:** https://streamlet.in
**Docs:** https://docs.streamlet.in
**NPM Package:** https://www.npmjs.com/package/@streamlet/sdk
**Starter Templates:** https://github.com/shangesh-tech/Streamlet-Templates

---

## REST API

**Base URL:** `https://api.streamlet.in`
**API Version:** v1.0.0

### Authentication

Every request requires two headers:

```
x-api-key: <your-api-key>
x-account-number: <your-account-number>
```

Obtain these from your Streamlet dashboard settings.

---

### Upload Video

**POST** `/api-key/start-video-processing`

Uploads a video file and queues it for HLS encoding, thumbnail generation, and optional caption generation.

**Form fields:**
- `video` (File, required) — the video file
- `videoTitle` (string, required) — used as the video ID prefix
- `generateCaptions` (boolean, optional) — enable automatic caption generation
- `captionLanguages` (string[], optional) — e.g. `["english","hindi","spanish","french","german","japanese"]`
- `autoAudioEnhancement` (boolean, optional) — noise reduction and audio normalisation
- `videoOptimization` (string, optional) — `fast` or `storage_saver`; storage saver creates smaller HLS files but takes longer
- `keepOriginal` (boolean, optional) — retain the original uploaded file alongside HLS output
- `generate4K` (boolean, optional) — encode a 4K variant (Builder / Pro plans)

**Response:**
```json
{
  "success": true,
  "videoId": "Launch Demo-1775211037986",
  "userId": "681b58c58d8c0a55b7c64b2c",
  "status": "queued",
  "message": "Video uploaded and queued for processing",
  "statusUrl": "/video-processing-status/Launch%20Demo-1775211037986"
}
```

---

### Video Status

**GET** `/api-key/video-processing-status/:videoId`

Poll this endpoint to check whether processing is complete.

**Response (completed):**
```json
{
  "success": true,
  "videoId": "Launch Demo-1775211037986",
  "status": "completed",
  "streamUrl": "https://cdn.streamlet.in/.../processed/master.m3u8",
  "thumbnail": "https://cdn.streamlet.in/.../processed/thumbnail.jpg",
  "durationSeconds": 27.81,
  "captions": {
    "en": "https://cdn.streamlet.in/.../captions.en.vtt",
    "hi": "https://cdn.streamlet.in/.../captions.hi.vtt"
  },
  "chapters": {
    "vtt": "https://cdn.streamlet.in/.../chapters.vtt",
    "json": "https://cdn.streamlet.in/.../chapters.json"
  }
}
```

---

### Upload Image

**POST** `/api-key/upload-image`

Uploads an image, converts it to WebP, and serves it via the global CDN.

**Form fields:**
- `image` (File, required) — JPEG, PNG, WebP, GIF, or AVIF

**Response:**
```json
{
  "success": true,
  "imageId": "product-banner-1775211037986",
  "cdnUrl": "https://cdn.streamlet.in/.../images/product-banner-1775211037986.webp",
  "width": 1200,
  "height": 630,
  "sizeBytes": 84320
}
```

---

### Health Check

**GET** `/health`

Returns `200 OK` when the API is operational.

---

## Plan Limits

| Plan    | Max Duration | Storage | Resolution | Caption quota / month |
|---------|-------------|---------|------------|-----------------------|
| Free    | 6 minutes   | 1 GB    | 480p       | 10 minutes            |
| Starter | Unlimited   | 50 GB   | 720p       | 5 hours               |
| Builder | Unlimited   | 200 GB  | 1080p      | 25 hours              |
| Pro     | Unlimited   | 500 GB  | 4K (2160p) | 50 hours              |

Free plan returns `DURATION_LIMIT_EXCEEDED` for videos longer than 6 minutes.

Caption quota resets on the 1st of each month. Uploads with captions enabled that exceed the quota return `CAPTION_QUOTA_EXCEEDED` (HTTP 403).

---

## NPM SDK — @streamlet/sdk

**Version:** v0.2.1
**Install:** `npm install @streamlet/sdk`
**NPM:** https://www.npmjs.com/package/@streamlet/sdk

### StreamletClient

```js
import { StreamletClient } from "@streamlet/sdk";

const client = new StreamletClient({
  apiKey: process.env.STREAMLET_API_KEY,
  accountNumber: process.env.STREAMLET_ACCOUNT_NUMBER,
});
```

### Upload a Video

```js
const result = await client.uploadVideo({
  file: videoFile,                          // File | Blob
  videoTitle: "Product Demo",
  generateCaptions: true,
  captionLanguages: ["english", "hindi"],
  autoAudioEnhancement: true,
  videoOptimization: "storage_saver",
  generate4K: false,
  keepOriginal: true,
});
// result.videoId, result.status, result.statusUrl
```

### Poll for Completion

```js
const status = await client.pollVideoStatus(result.videoId, {
  intervalMs: 3000,
  timeoutMs: 300000,
});
// status.streamUrl — HLS master playlist
// status.thumbnail — JPEG thumbnail URL
// status.captions  — { en: "...", hi: "..." }
```

### Upload an Image

```js
const img = await client.uploadImage({ file: imageFile });
// img.cdnUrl — WebP CDN URL ready to use in <img src>
```

### React Player Component

```jsx
import { StreamletPlayer } from "@streamlet/sdk/react";

<StreamletPlayer
  playbackUrl="https://cdn.streamlet.in/.../master.m3u8"
  posterUrl="https://cdn.streamlet.in/.../thumbnail.jpg"
  captions={[
    { src: "https://cdn.streamlet.in/.../captions.en.vtt", srclang: "en", label: "English" },
  ]}
  autoPlay={false}
  muted={false}
/>
```

---

## Starter Templates

All templates are at: https://github.com/shangesh-tech/Streamlet-Templates

| Template              | Stack                  | Purpose                                         |
|-----------------------|------------------------|-------------------------------------------------|
| Next.js Video Upload  | Next.js 16             | Upload video and poll for status via SDK        |
| Next.js Image Upload  | Next.js 16             | Upload images and use CDN URLs                  |
| Next.js Player        | Next.js 16             | HLS playback with StreamletPlayer               |
| Node.js Express       | Node.js / Express      | Backend proxy for Streamlet REST routes         |
| Go REST API           | Go                     | Video/image upload and status from Go           |
| Python REST API       | Python / FastAPI       | FastAPI integration for uploads                 |
| Rust REST API         | Rust / Axum            | Axum backend for Streamlet REST                 |
| Java REST API         | Java / Spring Boot     | Spring Boot integration                         |

---

## Contact

- Website: https://streamlet.in
- Email: contact@streamlet.in
- Twitter/X: https://x.com/shangesh_s
- LinkedIn: https://www.linkedin.com/in/shangesh-s/