# 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. `get_generation_status`: Query live status (`queued`, `processing`, `completed`, `failed`), progress, error codes, and download URLs for any media generation ID or job ID.
5. `check_credits`: Check available wallet balance and quotas.
6. `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`.

---

## 11. Error Taxonomy, Content Safety Policies & Credit Preservation Guarantee

Do0p enforces a **Zero-Risk Credit Preservation Guarantee**: Credits are deducted strictly upon verified delivery of pristine media. If an image or video generation is blocked by content safety filters, cluster capacity, or timeouts, your credits are immediately refunded (0 credits charged).

### Structured Error Payload (Machine-Readable JSON)
All API endpoints return structured errors adhering to OpenAI error specifications:
```json
{
  "status": "failed",
  "generation_id": "gen_88f9b2a1",
  "error": {
    "message": "Content Safety Notice: Your prompt was flagged by automated content safety filters (e.g. sensitive, adult, or policy-restricted concepts). Your credits were safely preserved. Please adjust your prompt description and try a different or milder concept.",
    "type": "content_policy_violation",
    "code": "unsafe_prompt",
    "recommendation": "Your prompt triggered content moderation filters. Please modify your prompt to use milder or artistic wording and try again."
  },
  "credits_refunded": true,
  "credits_charged": 0
}
```

### Error Codes & Automated Client Actions
| HTTP Status | Error Code | Trigger Condition | Recommended Machine Action |
|---|---|---|---|
| `400 Bad Request` | `unsafe_prompt` | Prompt contains adult, explicit, or restricted concepts | Rephrase prompt using artistic or metaphorical language. Do NOT immediately retry the exact same prompt. |
| `402 Payment Required` | `insufficient_credits` | Wallet balance is lower than required model credits | Top up wallet balance via Dashboard or reduce batch count / duration. |
| `429 Too Many Requests` | `rate_limit_exceeded` | Burst limit exceeded on current API key (120 req/min) | Exponential backoff (wait 2-5s) or distribute load across keys. |
| `502 Bad Gateway` | `generation_error` | Cluster GPU capacity or synthesis node error | Retry in 10-15 seconds or switch to a high-throughput model. |
| `504 Gateway Timeout` | `request_timeout` | Rendering took > 4 minutes due to high scene complexity | Simplify prompt or decrease resolution/steps and retry. |

### MCP Tool Status & Polling
When calling `get_generation_status(generation_id)`:
- Returns `status: "completed"` with `url` upon success.
- Returns `status: "failed"` with `code`, `message`, and `recommendation` upon failure, allowing agents to react programmatically rather than hanging.