# 2Slides API Documentation

## Base URL
```
https://2slides.com
```

## Authentication

All API requests require authentication using an API key. Include your API key in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

**Security Warning:** Never expose your API key in client-side code. All API calls should be made from your backend server.

---

## Best Practices & Common Workflows

### 1️⃣ Generate PowerPoint (PPT) Slides

Fast PPT generation using pre-built themes.

**Option A - Synchronous (recommended for < 10 pages):**
- Set `mode: "sync"`
- Wait for completion, get download URL immediately in response

**Option B - Asynchronous (for > 10 pages):**
- Set `mode: "async"`
- Get jobId immediately
- Poll `GET /api/v1/jobs/{jobId}` every 20-30 seconds until status is "success"
- Download file from downloadUrl

---

### 2️⃣ Search Theme Template + Generate PPT

Find the perfect theme before generating slides.

1. **Search themes:** `GET /api/v1/themes/search?query=business`
   - Browse available themes by keyword, get themeId
2. **Generate with selected theme:** `POST /api/v1/slides/generate`
   - Use themeId from search results

---

### 3️⃣ Create Custom Design Slides (PDF)

Generate slides with custom or default design from text input.

1. **Create slides (sync or async):** `POST /api/v1/slides/create-pdf-slides`
   - Async: returns jobId immediately
   - Sync: waits for completion and returns result directly
2. **Poll job status:** `GET /api/v1/jobs/{jobId}`
   - Check every 20-30 seconds until status is "success"
3. **Download file:** Use downloadUrl from job status response (valid for 1 hour)

---

### 4️⃣ Create Slides Like Reference Image

Generate slides matching a reference image style.

1. **Create slides (sync or async):** `POST /api/v1/slides/create-like-this`
   - Async: provide referenceImageUrl and content, returns jobId
   - Sync: waits for completion and returns result directly
2. **Poll job status:** `GET /api/v1/jobs/{jobId}`
   - Check every 20-30 seconds until status is "success"
3. **Download file:** Use downloadUrl from job status response (valid for 1 hour)

---

### 5️⃣ Add Voice Narration + Export Pages & Voices

Add AI voice narration to existing slides and export all assets.

1. **Prerequisites:** Must have a completed job from `create-pdf-slides` or `create-like-this`
2. **Generate voice narration (async only):** `POST /api/v1/slides/generate-narration`
   - Provide jobId from step 1, configure voice settings
3. **Poll job status:** `GET /api/v1/jobs/{jobId}`
   - Check every 20-30 seconds until status is "success"
   - Message will show "Voice narration generation in progress" during processing
4. **Export all assets (free):** `POST /api/v1/slides/download-slides-pages-voices`
   - Get ZIP file with pages/, voices/, and transcript.txt (no credits consumed)
5. **Download ZIP:** Use downloadUrl from response (valid for 1 hour)

---

### 💡 Pro Tips

- Use synchronous mode for quick generation (< 10 pages), asynchronous for larger presentations
- Poll job status every 20-30 seconds to avoid overwhelming the server (generation can take 1-3 minutes)
- Download URLs expire after 1 hour - download files promptly or request new URLs
- Voice narration requires 210 credits per page (10 for text + 200 for audio)
- Export pages & voices is completely free - no credits consumed
- Check job status message to distinguish between "Slides generation in progress" and "Voice narration generation in progress"
- For Nano Banana slides (create-like-this, create-pdf-slides): planning costs 10 credits per request, then generation costs 100 credits per slide (512px/1K/2K) or 200 credits per slide (4K)

---

## API Endpoints

### POST /api/v1/slides/generate

Generate PowerPoint slides using pre-built themes (Fast PPT).

**Request Body:**
```json
{
  "userInput": "Your presentation content",
  "themeId": "theme-id-from-search",
  "responseLanguage": "Auto",
  "mode": "sync"
}
```

**Parameters:**
- `userInput` (required): The content for your presentation
- `themeId` (required): Theme ID from /api/v1/themes/search
- `responseLanguage` (optional): Language code, default "Auto" (see Supported Languages below)
- `mode` (optional): "sync" or "async", default "sync"

**Response (Sync):**
```json
{
  "success": true,
  "data": {
    "jobId": "abc123",
    "status": "success",
    "downloadUrl": "https://...",
    "slidePageCount": 10
  }
}
```

**Response (Async):**
```json
{
  "success": true,
  "data": {
    "jobId": "abc123",
    "status": "processing",
    "message": "Slides generation started"
  }
}
```

**Credits:** 10 credits per page

---

### POST /api/v1/slides/create-like-this

Create slides matching the style of a reference image (Nano Banana).

**Request Body:**
```json
{
  "userInput": "Your presentation content",
  "referenceImageUrl": "https://example.com/reference.jpg",
  "responseLanguage": "Auto",
  "imageModel": "gemini-3-pro-image-preview",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "page": 10,
  "contentDetail": "concise",
  "mode": "async"
}
```

**Parameters:**
- `userInput` (required): Presentation content
- `referenceImageUrl` (required): URL of reference image
- `responseLanguage` (optional): Language code, default "Auto" (see Supported Languages below)
- `imageModel` (optional): "gemini-3-pro-image-preview" (default) or "gemini-3.1-flash-image-preview"
- `aspectRatio` (optional): 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 16:9). Extra ratios 1:4, 4:1, 1:8, 8:1 only supported by "gemini-3.1-flash-image-preview"
- `resolution` (optional): "1K", "2K", "4K" (default: 2K). "512px" only supported by "gemini-3.1-flash-image-preview"
- `page` (optional): Number of pages (0 = auto-detect, >=1 for specified count, max: 100)
- `contentDetail` (optional): "concise" or "standard" (default: concise)
- `mode` (optional): "sync" or "async" (default: async)

**Response:**
```json
{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "message": "Slides generation started",
    "jobUrl": "https://2slides.com/workspace?jobId=..."
  }
}
```

**Credits:**
- Planning: 10 credits per request
- 512px/1K/2K resolution: 100 credits per slide
- 4K resolution: 200 credits per slide

---

### POST /api/v1/slides/create-pdf-slides

Generate custom-designed slides from text input (Nano Banana).

**Request Body:**
```json
{
  "userInput": "Your presentation content",
  "designStyle": "Optional design instructions",
  "responseLanguage": "Auto",
  "imageModel": "gemini-3-pro-image-preview",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "page": 10,
  "contentDetail": "concise",
  "mode": "async"
}
```

**Parameters:**
- `userInput` (required): Presentation content
- `designStyle` (optional): Custom design instructions (leave empty for default style)
- `responseLanguage` (optional): Language code, default "Auto" (see Supported Languages below)
- `imageModel` (optional): "gemini-3-pro-image-preview" (default) or "gemini-3.1-flash-image-preview"
- `aspectRatio` (optional): 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 (default: 16:9). Extra ratios 1:4, 4:1, 1:8, 8:1 only supported by "gemini-3.1-flash-image-preview"
- `resolution` (optional): "1K", "2K", "4K" (default: 2K). "512px" only supported by "gemini-3.1-flash-image-preview"
- `page` (optional): Number of pages (0 = auto-detect, >=1 for specified count, max: 100)
- `contentDetail` (optional): "concise" or "standard" (default: concise)
- `mode` (optional): "sync" or "async" (default: async)

**Response:**
```json
{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "message": "Slides generation started",
    "jobUrl": "https://2slides.com/workspace?jobId=..."
  }
}
```

**Credits:**
- Planning: 10 credits per request
- 512px/1K/2K resolution: 100 credits per slide
- 4K resolution: 200 credits per slide

---

### POST /api/v1/slides/generate-narration

Add AI-generated voice narration to existing slides.

**Request Body (Single Speaker):**
```json
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "mode": "single",
  "speakerName": "John Doe",
  "voice": "Puck",
  "contentMode": "standard",
  "includeIntro": true
}
```

**Request Body (Multi Speaker):**
```json
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "mode": "multi",
  "speaker1Name": "Alice",
  "speaker2Name": "Bob",
  "speaker1Voice": "Aoede",
  "speaker2Voice": "Puck",
  "contentMode": "standard"
}
```

**Parameters:**
- `jobId` (required): UUID from create-like-this or create-pdf-slides (must be completed)
- `mode` (optional): "single" or "multi" (default: single)

**Single Speaker Mode:**
- `speakerName` (optional): Speaker name
- `voice` (optional): Voice name (see Supported Voices below)
- `contentMode` (optional): "concise" or "standard" (default: standard)
- `includeIntro` (optional): Include speaker introduction (default: true)

**Multi Speaker Mode:**
- `speaker1Name` (required): First speaker name
- `speaker2Name` (required): Second speaker name
- `speaker1Voice` (optional): First speaker voice (see Supported Voices below)
- `speaker2Voice` (optional): Second speaker voice (see Supported Voices below)
- `contentMode` (optional): "concise" or "standard" (default: standard)

**Response:**
```json
{
  "success": true,
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Voice narration generation started for job 550e8400-e29b-41d4-a716-446655440000"
}
```

**Supported Voices (30 total):**
Puck, Aoede, Charon, Kore, Fenrir, Zephyr, Leda, Orus, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat

**Credits:** 210 credits per page (10 for text generation + 200 for audio generation)

**Note:** This endpoint only supports async mode. Job must be completed and from Nano Banana (create-like-this or create-pdf-slides). Fast PPT jobs are not supported.

---

### POST /api/v1/slides/download-slides-pages-voices

Export all pages and voices as a ZIP file.

**Request Body:**
```json
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Parameters:**
- `jobId` (required): UUID from job with completed narration

**Response:**
```json
{
  "success": true,
  "data": {
    "downloadUrl": "https://...",
    "fileName": "presentation_pages_voices_2026-01-15T12-00-00.zip",
    "expiresIn": 3600
  }
}
```

**ZIP Contents:**
```
pages/
  page_01.png
  page_02.png
  ...
voices/
  page_01.wav
  page_02.wav
  ...
transcript.txt
```

**Credits:** Free (0 credits)

**Note:** Job must be completed with voice narration generated.

---

### GET /api/v1/jobs/{jobId}

Check status and get download URL for any job.

**Parameters:**
- `jobId` (path parameter): Job ID from any generation endpoint

**Response:**
```json
{
  "success": true,
  "data": {
    "jobId": "abc123",
    "status": "success",
    "message": "Slides generated successfully",
    "downloadUrl": "https://...",
    "slidePageCount": 10,
    "createdAt": 1234567890,
    "updatedAt": 1234567890,
    "duration": 45000,
    "jobUrl": "https://2slides.com/workspace?jobId=..."
  }
}
```

**Status Values:**
- `pending`: Job queued
- `processing`: Generation in progress
- `success`: Job completed
- `failed`: Job failed

**Note:**
- Message will indicate whether it's generating slides or voice narration
- For Nano Banana jobs (UUID jobId), jobUrl field is included
- Download URLs expire after 1 hour

---

### GET /api/v1/themes/search

Search and filter available slide themes for Fast PPT generation.

**Query Parameters:**
- `query` (required): Search keyword (e.g., "business", "minimal", "colorful")
- `limit` (optional): Max results, default 20, max 100

**Example:**
```
GET /api/v1/themes/search?query=business&limit=20
```

**Response:**
```json
{
  "success": true,
  "data": {
    "themes": [
      {
        "id": "cm5abc123",
        "name": "Business Professional",
        "description": "Clean and professional business theme",
        "tags": "business,professional,minimal",
        "themeURL": "https://2slides.com/templates/business-professional"
      }
    ],
    "total": 1
  }
}
```

**Credits:** Free (0 credits)

---

## Supported Languages

Pass the language code in the `responseLanguage` parameter. Default is "Auto" for automatic detection.

- **Auto** (Default) - Auto detect
- **English** - English
- **Spanish** - Español
- **Arabic** - العربية
- **Portuguese** - Português
- **Indonesian** - Bahasa Indonesia
- **Japanese** - 日本語
- **Russian** - Русский
- **Hindi** - हिंदी
- **French** - Français
- **German** - Deutsch
- **Greek** - Ελληνικά
- **Vietnamese** - Tiếng Việt
- **Turkish** - Türkçe
- **Thai** - ไทย
- **Polish** - Polski
- **Italian** - Italiano
- **Korean** - 한국어
- **Simplified Chinese** - 简体中文
- **Traditional Chinese** - 繁體中文

---

## Error Handling

### Error Response Format

```json
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

### Common Error Codes

- `INVALID_API_KEY` (401): Invalid or missing API key
- `INSUFFICIENT_CREDITS` (402): Not enough credits
- `INVALID_PARAMETER` (400): Invalid request parameters
- `JOB_NOT_FOUND` (404): Job ID not found
- `INVALID_JOB_ID` (400): Job ID format invalid (must be UUID for Nano Banana jobs)
- `JOB_NOT_COMPLETED` (400): Job is not completed yet
- `RATE_LIMIT_EXCEEDED` (429): Too many requests
- `INTERNAL_ERROR` (500): Server error

---

## Rate Limits

| Endpoint | Rate Limit |
|----------|-----------|
| /api/v1/slides/generate | 6 requests/minute |
| /api/v1/slides/create-like-this | 30 requests/minute |
| /api/v1/slides/create-pdf-slides | 30 requests/minute |
| /api/v1/slides/generate-narration | 30 requests/minute |
| /api/v1/slides/download-slides-pages-voices | 30 requests/minute |
| /api/v1/jobs/{id} | 10 requests/minute |
| /api/v1/themes/search | 30 requests/minute |

---

## Credits System

| Operation | Model | Credits |
|-----------|-------|---------|
| Generate PPT (Fast) | Fast PPT | 10 credits |
| Create Like This Planning | Nano Banana | 10 credits / request |
| Create Like This | Nano Banana (512px/1K/2K) | 100 credits |
| Create Like This | Nano Banana (4K) | 200 credits |
| Create PDF Slides Planning | Nano Banana | 10 credits / request |
| Create PDF Slides | Nano Banana (512px/1K/2K) | 100 credits |
| Create PDF Slides | Nano Banana (4K) | 200 credits |
| Voice Text Generation | - | 10 credits |
| Voice Audio Generation | - | 200 credits |
| Export Pages & Voices | - | Free (0 credits) |
| Search Themes | - | Free (0 credits) |
| Check Job Status | - | Free (0 credits) |

**Note:**
- Voice narration requires 210 credits per page total (10 for text + 200 for audio)
- Example: A 5-page Nano Banana presentation (1K/2K) with voice narration costs: 10 + (100 × 5) + (210 × 5) = 1,560 credits

---

## Support

For questions or issues:
- Documentation: https://2slides.com/api
- Contact: service@2slides.com

---

*Generated: 2026-05-04T06:03:46.736Z*
*Version: 1.0*