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

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

Response:

{
  "success": true,
  "job_id": "job_abc123",
  "status": "queued",
  "position": 1
}

---

2. Analyze Image

POST /gemini/analyze-image

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

---

3. Edit Image

POST /gemini/edit-image

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

---

4. Generate Video

POST /gemini/generate-video

{
  "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

{
  "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:

{
  "status": "queued",
  "position": 3
}

Processing:

{
  "status": "processing",
  "started_at": "2024-12-12T13:00:00Z"
}

Completed (Text/Image/Analyze):

{
  "status": "completed",
  "output": {
    "text": "Here is your poem..."
  }
}

Completed (Video):

{
  "status": "completed",
  "output": {
    "filename": "video_abc123.mp4"
  },
  "download_url": "/gemini/download/job_abc123"
}

Failed:

{
  "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.

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

---

Client Polling Example (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