# PigenAI Developer Platform & API Documentation (Full Specification)

> Comprehensive reference documentation for the PigenAI Developer Platform (https://www.pigenai.art/). Built for AI search engines, automated agents, coding assistants, and software engineers.

---

## 1. System Overview

PigenAI is a low-latency, scalable AI media generation API platform providing direct access to 17+ state-of-the-art text-to-image, image-to-image, and video generation foundation models.

- **Website**: https://www.pigenai.art/
- **Developer Console**: https://www.pigenai.art/developers
- **API Models Catalog**: https://www.pigenai.art/api/models
- **API Base URL**: `https://api.pigenai.art/v1`
- **Supported Paradigms**: REST HTTP/JSON & OpenAI SDK Drop-in Compatibility
- **Billing Model**: Direct pay-as-you-go USD micro-pricing. No recurring subscriptions required.

---

## 2. Model Pricing & Full Architecture Catalog (2026)

All generation costs are denominated directly in USD ($). Micro-pricing is calculated with up to 4 decimal precision.

### A. Text-to-Image Foundation Models
| Model ID | Input Modalities | Output | Unit Price (USD) | Price Advantage | Key Parameters |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `stabilityai/sdxl-turbo` | `text` | `image` | **$0.0008 / image** | **68% cheaper than market standard** | `prompt`, `size`, `seed` |
| `black-forest-labs/flux-1-schnell` | `text` | `image` | **$0.0030 / image** | Fast 4-step synthesis | `prompt`, `size`, `seed` |
| `HiDream-ai/HiDream-I1-Fast` | `text` | `image` | **$0.0050 / image** | **45% cheaper than market standard** | `prompt`, `size`, `seed` |
| `bytedance/seedance-1-fast` | `text` | `image` | **$0.0180 / image** | Fast ByteDance generation | `prompt`, `size`, `seed` |
| `google/imagen-4-fast` | `text` | `image` | **$0.0240 / image** | Google Imagen 4 photorealism | `prompt`, `size`, `seed`, `aspect_ratio` |
| `recraft/recraft-v4` | `text` | `image` | **$0.0270 / image** | **~25-30% cheaper than market standard** | `prompt`, `size`, `seed`, `art_style` |
| `bytedance/seedance-1-pro` | `text` | `image` | **$0.0300 / image** | Pro-grade photorealism | `prompt`, `size`, `seed` |

### B. Image-to-Image & Editing Models
| Model ID | Input Modalities | Output | Unit Price (USD) | Price Advantage | Key Parameters |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `prunaai/P-Image-Upscale` | `image` | `image` | **$0.0120 / image** | 2K/4K super-resolution upscaling | `image`, `size` |
| `qwen/qwen-image-edit` | `text`, `image` | `image` | **$0.0150 / image** | **28% cheaper than market standard** | `image`, `prompt`, `size`, `quality` |
| `krea/krea-2-turbo` | `text`, `image` | `image` | **$0.0230 / image** | Real-time image restyling | `image`, `prompt`, `size`, `quality` |
| `qwen/qwen-image-layered` | `text`, `image` | `image` | **$0.0250 / image** | Layered image decomposition | `image`, `prompt`, `size`, `quality` |
| `wan/wan-2.7-image` | `text`, `image` | `image` | **$0.0340 / image** | Advanced multi-aspect image transformation | `image`, `prompt`, `size` |

### C. Text-to-Video & Image-to-Video Models
| Model ID | Input Modalities | Output | Unit Price (USD) | Price Advantage | Key Parameters |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `bytedance/seedance-1-pro-fast` | `text`, `image` | `video` | **$0.0320 / second** | **~34% cheaper than market standard** | `prompt`, `image`, `seconds`, `size` |
| `xAI/grok-imagine-video` | `text`, `image` | `video` | **$0.0450 / second** | **EXCLUSIVE Service**, cheaper than X API | `prompt`, `image`, `seconds`, `size` |
| `kling/kling-2.1-standard` | `text`, `image` | `video` | **$0.0550 / second** | **~31% cheaper than market standard** | `prompt`, `image`, `seconds`, `size` |
| `veo-3.1-fast` | `text`, `image` | `video` | **$0.0750 / second** | Google Veo 3.1 Fast HD video | `prompt`, `image`, `seconds`, `size` |
| `kling/kling-2.1-pro` | `text`, `image` | `video` | **$0.0900 / second** | Pro cinema camera control | `prompt`, `image`, `seconds`, `size` |

---

## 3. Account Balance, Top-Ups & Refund Guarantee

### Direct USD Balance Top-Up Packs
API credits operate on a direct USD balance model. Top-up packs are purchased through the Developer Dashboard via secure checkout:
1. **Starter Pack**: $5.00 ($5.00 Balance)
2. **Builder Pack**: $10.00 ($10.50 Balance, **+5% bonus**)
3. **Scale Pack**: $25.00 ($27.50 Balance, **+10% bonus**)
4. **Mega Pack**: $50.00 ($57.50 Balance, **+15% bonus**)

### Automated Refund Guarantee
If any API request fails due to an upstream model error, timeout, or service interruption, the exact amount deducted is automatically refunded back to the developer's USD balance within milliseconds.

---

## 4. Endpoints & API Reference

### 1. Generate Image (Text-to-Image)
- **Method**: `POST`
- **Path**: `/v1/images/generations`
- **Headers**:
  - `Authorization: Bearer pk_live_YOUR_API_KEY`
  - `Content-Type: application/json`

**Request Body**:
```json
{
  "model": "stabilityai/sdxl-turbo",
  "prompt": "A futuristic cybernetic tiger in neon lights, ultra realistic 8k",
  "size": "1024x1024",
  "response_format": "url"
}
```

**Response (200 OK)**:
```json
{
  "created": 1724457600,
  "data": [
    {
      "url": "https://cdn.pigenai.art/generations/img_9a8b7c6d5e4f.png",
      "model": "stabilityai/sdxl-turbo",
      "cost_usd": 0.0008
    }
  ]
}
```

---

### 2. Edit Image (Image-to-Image)
- **Method**: `POST`
- **Path**: `/v1/images/edits`

**Request Body**:
```json
{
  "model": "qwen/qwen-image-edit",
  "image": "https://example.com/source-photo.jpg",
  "prompt": "Change the background to a tropical beach at sunset",
  "size": "1024x1024"
}
```

**Response (200 OK)**:
```json
{
  "created": 1724457600,
  "data": [
    {
      "url": "https://cdn.pigenai.art/generations/edit_3f2e1d0c.png",
      "model": "qwen/qwen-image-edit",
      "cost_usd": 0.0150
    }
  ]
}
```

---

### 3. Generate Video (Text-to-Video & Image-to-Video)
- **Method**: `POST`
- **Path**: `/v1/videos/generations`

**Request Body**:
```json
{
  "model": "bytedance/seedance-1-pro-fast",
  "prompt": "Cinematic camera movement through dynamic lighting scenery",
  "size": "1280x720",
  "seconds": 5
}
```

**Response (200 OK)**:
```json
{
  "created": 1724457600,
  "data": [
    {
      "url": "https://cdn.pigenai.art/generations/vid_8c7b6a5e.mp4",
      "model": "bytedance/seedance-1-pro-fast",
      "seconds": 5,
      "cost_usd": 0.1600
    }
  ]
}
```

---

### 4. Check USD Balance
- **Method**: `GET`
- **Path**: `/v1/balance`

**Response (200 OK)**:
```json
{
  "object": "balance",
  "balance_usd": 14.50,
  "tier": "developer"
}
```

---

### 5. List Available Models
- **Method**: `GET`
- **Path**: `/v1/models`

**Response (200 OK)**:
```json
{
  "object": "list",
  "data": [
    {
      "id": "stabilityai/sdxl-turbo",
      "object": "model",
      "created": 1701129600,
      "owned_by": "stabilityai",
      "pricing": {
        "marked": 0.0008
      },
      "type": "image"
    }
  ]
}
```

---

### 6. Usage Analytics
- **Method**: `GET`
- **Path**: `/v1/usage?days=30`

**Response (200 OK)**:
```json
{
  "total_requests": 1420,
  "successful": 1412,
  "failed": 8,
  "total_cost_usd": 18.3420,
  "avg_latency_ms": 1150
}
```

---

## 5. Integration Code Snippets

### Python with Official OpenAI SDK
```python
from openai import OpenAI

client = OpenAI(
    api_key="pk_live_YOUR_API_KEY",
    base_url="https://api.pigenai.art/v1"
)

# Text-to-Image with SDXL Turbo ($0.0008)
response = client.images.generate(
    model="stabilityai/sdxl-turbo",
    prompt="Futuristic cityscape with flying vehicles at night, 8k octane render",
    size="1024x1024"
)
print("Image URL:", response.data[0].url)
```

### Node.js / TypeScript with Fetch
```typescript
async function generateMedia() {
  const res = await fetch("https://api.pigenai.art/v1/images/generations", {
    method: "POST",
    headers: {
      "Authorization": "Bearer pk_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "black-forest-labs/flux-1-schnell",
      prompt: "Ultra-detailed portrait of a cyberpunk explorer",
      size: "1024x1024"
    }),
  });

  const json = await res.json();
  console.log("Result URL:", json.data[0].url);
}
```

---

## 6. HTTP Error Codes Reference

| HTTP Status | Error Type | Meaning | Suggested Action |
| :--- | :--- | :--- | :--- |
| `400` | `invalid_request` | Invalid parameters or unsupported image dimensions | Check supported parameters in `/v1/models` |
| `401` | `authentication_error` | Missing, malformed, or revoked API key | Verify `Authorization: Bearer pk_live_...` |
| `402` | `insufficient_balance` | Account USD balance is insufficient | Top up balance at https://www.pigenai.art/developers |
| `429` | `rate_limit_exceeded` | Exceeded rate limit per minute | Implement exponential backoff or request higher tier |
| `500` | `internal_error` | Upstream model failure (auto-refunded) | Automatic refund processed; retry request |

---

## 7. Model Direct Links
- [SDXL Turbo ($0.0008/img)](https://www.pigenai.art/api/models/stabilityai/sdxl-turbo)
- [Flux Schnell ($0.0030/img)](https://www.pigenai.art/api/models/black-forest-labs/flux-1-schnell)
- [HiDream I1 Fast ($0.0050/img)](https://www.pigenai.art/api/models/HiDream-ai/HiDream-I1-Fast)
- [Seedance 1 Fast ($0.0180/img)](https://www.pigenai.art/api/models/bytedance/seedance-1-fast)
- [Imagen 4 Fast ($0.0240/img)](https://www.pigenai.art/api/models/google/imagen-4-fast)
- [Recraft v4 ($0.0270/img)](https://www.pigenai.art/api/models/recraft/recraft-v4)
- [Seedance 1 Pro ($0.0300/img)](https://www.pigenai.art/api/models/bytedance/seedance-1-pro)
- [P-Image-Upscale ($0.0120/img)](https://www.pigenai.art/api/models/prunaai/P-Image-Upscale)
- [Qwen Image Edit ($0.0150/img)](https://www.pigenai.art/api/models/qwen/qwen-image-edit)
- [Krea 2 Turbo ($0.0230/img)](https://www.pigenai.art/api/models/krea/krea-2-turbo)
- [Qwen Image Layered ($0.0250/img)](https://www.pigenai.art/api/models/qwen/qwen-image-layered)
- [Wan 2.7 Image ($0.0340/img)](https://www.pigenai.art/api/models/wan/wan-2.7-image)
- [Seedance 1 Pro Fast ($0.0320/sec)](https://www.pigenai.art/api/models/bytedance/seedance-1-pro-fast)
- [Grok Imagine Video ($0.0450/sec)](https://www.pigenai.art/api/models/xAI/grok-imagine-video)
- [Kling 2.1 Standard ($0.0550/sec)](https://www.pigenai.art/api/models/kling/kling-2.1-standard)
- [Veo 3.1 Fast ($0.0750/sec)](https://www.pigenai.art/api/models/veo-3.1-fast)
- [Kling 2.1 Pro ($0.0900/sec)](https://www.pigenai.art/api/models/kling/kling-2.1-pro)