api doc

docs/GEMINI_API.md

@@ -0,0 +1,230 @@
+# 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 |