# Do0p AI Media Generation Platform — Complete Developer & Agent Reference Manual

## 1. Executive Summary & Base Endpoints
Do0p is an enterprise generative media platform powered by Google Flow and Veo diffusion models with automated mathematical reverse-alpha watermark removal.
- **REST Base URL**: `https://do0p.com/api/v1`
- **MCP SSE URL**: `https://do0p.com/api/mcp?key=YOUR_API_KEY`
- **OpenAPI 3.0 Spec**: `https://do0p.com/api/v1/openapi.json`
- **Terminal MCP Installer**: `curl -sSL "https://do0p.com/api/mcp/install?key=YOUR_API_KEY" | bash`

---

## 2. Authentication & Rate Limiting
- **Authentication**: All API requests require a Bearer token in the HTTP Authorization header:
  `Authorization: Bearer doop_live_...`
- **Rate Limit**: 120 requests per minute per IP address on all `/api/` routes.
- **Rate Limit Headers**:
  - `Retry-After`: Number of seconds to wait before retrying when `HTTP 429 Too Many Requests` is returned.
- **Status Codes**:
  - `200 OK`: Request succeeded.
  - `400 Bad Request`: Missing or invalid parameters.
  - `401 Unauthorized`: Missing or invalid API key.
  - `402 Payment Required`: Insufficient credit balance.
  - `429 Too Many Requests`: Rate limit threshold exceeded.
  - `500 Internal Server Error`: Backend failure (credits auto-refunded).

---

## 3. Image Generation (`POST /api/v1/images/generations`)
Synthesizes high-fidelity generative imagery powered by Google Flow Nano Banana models with automatic mathematical watermark removal. Drop-in compatible with OpenAI SDKs.

### Models & Pricing
- `nano-banana-pro` (Gemini 3 Pro Image): 1.0 Credit ($0.010) — 2048x2048 native 2K resolution, state-of-the-art visual fidelity, photorealism, multi-subject grounding.
- `nano-banana-2` (Gemini 3.1 Flash Image): 0.8 Credits ($0.008) — 2048x2048 native 2K resolution, high-speed latency.
- `nano-banana-2-lite` (Gemini 3.1 Flash Lite): 0.5 Credits ($0.005) — 1024x1024 resolution, ultra-low latency.

### Request Body (JSON)
| Field | Type | Default | Description |
|---|---|---|---|
| `prompt` | string | *required* | Text description of the image to generate. |
| `model` | string | `"nano-banana-pro"` | `nano-banana-pro`, `nano-banana-2`, or `nano-banana-2-lite`. |
| `size` | string | `"2048x2048"` | Target size or aspect ratio: `2048x2048` (1:1), `1792x1024` (16:9), `1024x1792` (9:16), `1024x768` (4:3), `768x1024` (3:4), `1024x1024`. |
| `n` | integer | `1` | Number of images to generate (1 to 4). |
| `quality` | string | `"hd"` | `"standard"` (1K) or `"hd"` (2K Lanczos Super-Resolution). |
| `images_base64` | array[string] | `null` | Optional array of up to 5 base64 data URLs for reference guidance. |
| `seed` | integer | `random` | Deterministic random seed (0 to 4294967295). |
| `auto_remove_watermark` | boolean | `true` | When true, strips watermarks losslessly before returning. |

### cURL Example
```bash
curl -X POST https://do0p.com/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Architectural studio render of a brutalist concrete pavilion in a moss garden, rainy atmosphere, 8k",
    "model": "nano-banana-pro",
    "size": "2048x2048",
    "n": 1,
    "quality": "hd",
    "auto_remove_watermark": true
  }'
```

### Python (OpenAI SDK Drop-in) Example
```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://do0p.com/api/v1"
)

response = client.images.generate(
    model="nano-banana-pro",
    prompt="Cybernetic panther prowling on neon rooftop in rainy Tokyo, cinematic 8k",
    size="2048x2048",
    n=1
)

print("Watermark-Free Deliverable:", response.data[0].url)
```

### TypeScript / Node.js Example
```typescript
const res = await fetch("https://do0p.com/api/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.DO0P_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "Vibrant macro photograph of a transparent crystal beetle on a neon flower, 8k",
    model: "nano-banana-pro",
    size: "2048x2048",
    n: 1
  })
});
const data = await res.json();
console.log("Image URL:", data.data[0].url);
```

### Response (JSON)
```json
{
  "created": 1741234567,
  "model": "nano-banana-pro",
  "credits_deducted": 1.0,
  "credits_remaining": 149.0,
  "data": [
    {
      "url": "https://do0p.com/media/clean_flow_crystal_1741234567.png",
      "resolution": "2048x2048",
      "latency_ms": 1420
    }
  ]
}
```

---

## 4. 2K Image Upscaler (`POST /api/v1/images/upscale`)
Upscales images to 2K resolution (2048px+) using Lanczos anti-aliasing interpolation. Cost: 0.5 credits.

### Request Body (JSON)
| Field | Type | Description |
|---|---|---|
| `url` | string | Direct HTTP/HTTPS URL of the image to upscale. |
| `image_base64` | string | Base64 data URI of the image (if `url` is not provided). |
| `scale` | number | Scaling multiplier (default `2`). |

### cURL Example
```bash
curl -X POST https://do0p.com/api/v1/images/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://do0p.com/media/sample_original.png",
    "scale": 2
  }'
```

### Response (JSON)
```json
{
  "success": true,
  "url": "https://do0p.com/media/upscaled_1741234999_sample.png",
  "resolution": "2048x2048",
  "original_resolution": "1024x1024"
}
```

---

## 5. Video Synthesis (`POST /api/v1/videos/generations` & Polling)
Synthesizes cinema-grade 720p HD videos (1280x720 landscape, 720x1280 portrait @ 24fps) powered by Google Veo temporal diffusion with automated watermark removal.

### Pricing by Duration
- **4 Seconds**: 7 Credits ($0.07)
- **6 Seconds**: 10 Credits ($0.10)
- **8 Seconds**: 14 Credits ($0.14)
- **10 Seconds**: 18 Credits ($0.18)

### Synthesis Modes
1. **Frames Mode (`video_mode: "frames"`)**:
   - Accepts `start_image_base64` (first frame) and optional `end_image_base64` (last frame).
   - The temporal engine synthesizes motion and camera trajectory between keyframes.
2. **Ingredients Mode (`video_mode: "ingredients"`)**:
   - Accepts up to 5 reference images in `images_base64`.
   - Preserves character, wardrobe, lighting, or product consistency throughout the clip.

### Request Body (JSON)
| Field | Type | Default | Description |
|---|---|---|---|
| `prompt` | string | *required* | Motion and scene description. |
| `model` | string | `"omni-1.1-flash"` | Flagship Google Veo temporal diffusion model. |
| `video_mode` | string | `"frames"` | `"frames"` or `"ingredients"`. |
| `duration` | integer | `4` | `4`, `6`, `8`, or `10` seconds. |
| `resolution` | string | `"720p"` | 720p High Definition Master. |
| `aspect` | string | `"landscape"` | `"landscape"` (16:9, 1280x720) or `"portrait"` (9:16, 720x1280). |
| `start_image_base64` | string | `null` | Base64 image for the start keyframe (Frames mode). |
| `end_image_base64` | string | `null` | Base64 image for the end keyframe (Frames mode). |
| `images_base64` | array[string] | `null` | Up to 5 base64 reference images (Ingredients mode). |

### Step 1: Submit Video Job
```bash
curl -X POST https://do0p.com/api/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Camera drifts smoothly forward through foggy bamboo forest towards a temple gateway, cinematic lighting, 24fps",
    "model": "omni-1.1-flash",
    "video_mode": "frames",
    "duration": 6,
    "resolution": "720p",
    "aspect": "landscape"
  }'
```
**Submit Response (HTTP 200)**:
```json
{
  "job_id": "gen_video_174123499",
  "status": "processing",
  "credits_deducted": 10,
  "credits_remaining": 139
}
```

### Step 2: Poll Video Status (`GET /api/v1/videos/generations/{id}`)
```bash
curl -X GET https://do0p.com/api/v1/videos/generations/gen_video_174123499 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Completed Response (HTTP 200)**:
```json
{
  "job_id": "gen_video_174123499",
  "status": "completed",
  "prompt": "Camera drifts smoothly forward through foggy bamboo forest towards a temple gateway...",
  "duration": 6,
  "video_url": "https://do0p.com/media/clean_174123499_bamboo.mp4",
  "created_at": "2026-09-16T12:00:00.000Z"
}
```
*(If the job fails, credits are automatically refunded to your balance and status reports `"failed"` with the error description).*

---

## 6. Lossless Watermark Inversion (`POST /api/v1/watermark/remove`)
Inverts Google Flow and Gemini watermarks losslessly using the compiled Go engine (`gemini-omni`). Solves the mathematical inverse alpha channel equation to recover 100% of underlying pixels without blur or hallucination. Cost: 0.2 credits ($0.002).

### Option A: JSON with URL
```bash
curl -X POST https://do0p.com/api/v1/watermark/remove \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://do0p.com/media/watermarked_input.png"
  }'
```

### Option B: Multipart File Upload
```bash
curl -X POST https://do0p.com/api/v1/watermark/remove \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/watermarked_video.mp4"
```

### Response (JSON)
```json
{
  "success": true,
  "cleaned_url": "https://do0p.com/media/clean_1741235432_ab12cd.png",
  "raw_url": "https://do0p.com/media/input_1741235432_ab12cd.png",
  "duration_ms": 68,
  "credits_deducted": 0.2
}
```

---

## 7. Account Credit Balances (`GET /api/v1/user/credits`)
Programmatically inspect wallet balance, approximate USD balance value, and recent credit history. Free of charge.

### Request
```bash
curl -X GET https://do0p.com/api/v1/user/credits \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (JSON)
```json
{
  "user_id": "usr_94381",
  "email": "developer@company.com",
  "credits_balance": 139.0,
  "approx_usd_value": "1.39",
  "recent_transactions": [
    {
      "id": "tx_8412",
      "amount": -10,
      "type": "GENERATION",
      "description": "Video Generation (6s): Camera drifts...",
      "createdAt": "2026-09-16T12:00:00.000Z"
    }
  ]
}
```

---

## 8. Live Model Catalog (`GET /api/v1/models`)
Retrieve the active list of generative models, supported modalities, and live credit rates. Free of charge.

### Request
```bash
curl -X GET https://do0p.com/api/v1/models
```

### Response (JSON)
```json
{
  "object": "list",
  "data": [
    {
      "id": "nano-banana-pro",
      "name": "Nano Banana Pro",
      "type": "IMAGE",
      "description": "Gemini 3 Pro Image foundation. Native 2K.",
      "credit_cost": 1.0,
      "price_usd": 0.01,
      "badge": "2K Pro",
      "is_featured": true
    },
    {
      "id": "omni-1.1-flash",
      "name": "Omni 1.1 Flash",
      "type": "VIDEO",
      "description": "Google Veo temporal diffusion. 720p HD Master.",
      "credit_cost": 7.0,
      "price_usd": 0.07,
      "duration_seconds": 4,
      "badge": "720p HD",
      "is_featured": true
    }
  ]
}
```

---

## 9. Customer Webhooks (Asynchronous Events)
Configure webhooks in your [Dashboard](/dashboard/webhooks) to receive automated HTTP POST notifications when generation jobs finish.

### Event Types
- `generation.completed` — Image synthesis or upscale finished.
- `generation.failed` — Image generation failed (credits auto-refunded).
- `video.completed` — Asynchronous video synthesis finished.
- `video.failed` — Video generation failed (credits auto-refunded).

### Webhook Payload Example
```json
{
  "event": "video.completed",
  "timestamp": "2026-09-16T12:00:30.000Z",
  "data": {
    "job_id": "gen_video_174123499",
    "status": "completed",
    "model": "omni-1.1-flash",
    "duration": 6,
    "video_url": "https://do0p.com/media/clean_174123499_bamboo.mp4",
    "credits_deducted": 10
  }
}
```

### Signature Verification (`X-Do0p-Signature`)
Every webhook delivery includes an `X-Do0p-Signature` header calculated using HMAC-SHA256 of the raw request body with your webhook secret:
```javascript
// Node.js verification snippet
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signatureHeader));
}
```

---

## 10. Model Context Protocol (MCP) & 1-Click Integrations
Do0p natively exposes an MCP server for AI agents and developer tooling.

### Remote SSE Endpoint
```
https://do0p.com/api/mcp?key=YOUR_API_KEY
```

### Available MCP Tools
1. `generate_flow_image`: Synthesize 1-4 watermark-free 2K images with Nano Banana Pro/2/2-Lite.
2. `generate_flow_video`: Synthesize 720p HD Veo videos in Frames (start/end frame) or Ingredients mode.
3. `remove_watermark`: Losslessly invert Google Flow watermarks from any image or video URL.
4. `check_credits`: Check available wallet balance and quotas.
5. `list_models`: Retrieve available models and live pricing.

### Client Setup Guides
- **Cursor IDE**:
  Open **Settings > Features > MCP > Add New MCP Server**. Set Type to `SSE` and enter `https://do0p.com/api/mcp?key=YOUR_API_KEY`.
- **Claude Desktop (1-Click Terminal Command)**:
  `curl -sSL "https://do0p.com/api/mcp/install?key=YOUR_API_KEY" | bash`
- **ChatGPT Custom GPTs**:
  In ChatGPT Action configuration, import OpenAPI schema from URL: `https://do0p.com/api/v1/openapi.json` and set Authentication to Bearer with your API key.
- **Open WebUI / LibreChat**:
  Set OpenAI Base URL to `https://do0p.com/api/v1` and set API Key to your Do0p key. Models: `nano-banana-pro`, `omni-1.1-flash`.