docs/GEMINI_API.md

# Gemini API - Client Integration Guide

## Authentication

All endpoints require JWT authentication via Google Sign-In.

```
Authorization: Bearer <your_jwt_token>
```

---

## Endpoints

### 1. Generate Text
**POST** `/gemini/generate-text`

```json
{
  "prompt": "Write a poem about the moon",
  "model": "gemini-2.5-flash"  // optional
}
```

**Response:**
```json
{
  "success": true,
  "job_id": "job_abc123",
  "status": "queued",
  "position": 1
}
```

---

### 2. Analyze Image
**POST** `/gemini/analyze-image`

```json
{
  "base64_image": "<base64_encoded_image>",
  "mime_type": "image/jpeg",
  "prompt": "What's in this image?"
}
```

---

### 3. Edit Image
**POST** `/gemini/edit-image`

```json
{
  "base64_image": "<base64_encoded_image>",
  "mime_type": "image/jpeg",
  "prompt": "Make the sky purple"
}
```

---

### 4. Generate Video
**POST** `/gemini/generate-video`

```json
{
  "base64_image": "<base64_encoded_image>",
  "mime_type": "image/jpeg",
  "prompt": "Make this scene come alive with gentle motion",
  "aspect_ratio": "16:9",    // or "9:16"
  "resolution": "720p",       // or "1080p"
  "number_of_videos": 1       // 1-4
}
```

---

### 5. Generate Animation Prompt
**POST** `/gemini/generate-animation-prompt`

```json
{
  "base64_image": "<base64_encoded_image>",
  "mime_type": "image/png",
  "custom_prompt": null  // optional
}
```

---

## Polling for Results

All requests return a `job_id`. Poll for status:

**GET** `/gemini/job/{job_id}`

### Status Flow:
```
queued → processing → completed / failed
```

### Response Examples:

**Queued:**
```json
{
  "status": "queued",
  "position": 3
}
```

**Processing:**
```json
{
  "status": "processing",
  "started_at": "2024-12-12T13:00:00Z"
}
```

**Completed (Text/Image/Analyze):**
```json
{
  "status": "completed",
  "output": {
    "text": "Here is your poem..."
  }
}
```

**Completed (Video):**
```json
{
  "status": "completed",
  "output": {
    "filename": "video_abc123.mp4"
  },
  "download_url": "/gemini/download/job_abc123"
}
```

**Failed:**
```json
{
  "status": "failed",
  "error": "API rate limit exceeded"
}
```

---

## Download Video

**GET** `/gemini/download/{job_id}`

Returns the video file directly.

---

## Cancel Job

**POST** `/gemini/job/{job_id}/cancel`

Only works for `queued` jobs.

```json
{
  "success": true,
  "status": "cancelled"
}
```

---

## Client Polling Example (JavaScript)

```javascript
async function generateText(prompt) {
  // 1. Submit job
  const response = await fetch('/gemini/generate-text', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ prompt })
  });
  const { job_id } = await response.json();

  // 2. Poll until done
  while (true) {
    const status = await fetch(`/gemini/job/${job_id}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    }).then(r => r.json());

    if (status.status === 'completed') {
      return status.output.text;
    }
    if (status.status === 'failed') {
      throw new Error(status.error);
    }
    
    // Wait before next poll
    await new Promise(r => setTimeout(r, 2000));
  }
}
```

---

## Priority Tiers

Jobs are processed with different priorities:

| Job Type | Priority | Poll Interval |
|----------|----------|---------------|
| text, analyze, animation_prompt | Fast | ~5 sec |
| image, edit_image | Medium | ~30 sec |
| video | Slow | ~60 sec |

---

## Error Codes

| Code | Meaning |
|------|---------|
| 401 | Unauthorized - Invalid/expired token |
| 402 | Insufficient credits |
| 404 | Job not found |
| 429 | Rate limit exceeded |