# Mobbi AI - Complete Product Reference

> Free AI-powered video, image, and 3D generation platform with 20+ tools and 30+ models

_Last updated: 2026-06-04_

## Table of Contents

1. [Platform Overview](#platform-overview)
2. [Video Generation Tools](#video-generation-tools)
3. [Image Generation Tools](#image-generation-tools)
4. [3D Generation Tools](#3d-generation-tools)
5. [Editing Tools](#editing-tools)
6. [Video Effects](#video-effects)
7. [Supported Models](#supported-models)
8. [Pricing & Credits](#pricing--credits)
9. [Languages & Availability](#languages--availability)
10. [Renderful API Reference](#renderful-ai---complete-api-reference-for-ai-agents)

---

## Platform Overview

Mobbi AI (https://mobbi.ai) is a browser-based creative AI platform. Users generate and edit videos, images, and 3D models through an intuitive web interface. No software download required.

**Key Facts:**
- 20+ AI creative tools in one platform
- 30+ AI models including Sora 2, Kling AI, Veo 3.1, Flux, GPT Image
- Free daily credits, no credit card required
- All generated content licensed for commercial use
- Available in 16 languages
- Works on desktop and mobile browsers

**Website:** https://mobbi.ai
**Pricing:** https://mobbi.ai/pricing

---

## Video Generation Tools

### Text to Video
**URL:** https://mobbi.ai/text-to-video
Generate videos from text descriptions. Write a prompt describing the scene, action, and style, and AI models produce matching video content.

- **Models available:** Sora 2, Sora 2 Pro, Kling AI (v1 through v2.6, O1), Veo 3.1, Veo 3.1 Fast, Hailuo 2.3, Hailuo 2.3 Fast, Seedance 1.0 Lite/Pro, Seedance 1.5 Pro, WAN 2.5, WAN 2.6, Vidu Q2
- **Resolutions:** Up to 4K depending on model
- **Durations:** 4 seconds to 60+ seconds depending on model
- **Aspect ratios:** 16:9, 9:16, 1:1
- **Generation time:** 1-5 minutes typical

### Image to Video
**URL:** https://mobbi.ai/image-to-video
Animate static images into dynamic videos. Upload a photo and the AI generates natural motion, camera movement, and scene dynamics.

- **Input formats:** JPG, PNG, WebP (recommended 1024x1024+)
- **Motion control:** Text prompts guide animation direction and style
- **Use cases:** Product showcases, social media content, photo animation, e-commerce video

### Video Extender
**URL:** https://mobbi.ai/video-extender
Extend videos beyond their original length by generating new continuation frames. The AI maintains scene consistency, motion patterns, and visual style.

- **Extension length:** 2-10 seconds per generation
- **Works with:** Real footage and AI-generated videos
- **Quality:** Seamless transitions between original and extended content

### Marketing Studio
**URL:** https://mobbi.ai/marketing-studio
Create professional video advertisements from product URLs. The AI extracts product information, images, and selling points to produce platform-optimized video ads.

- **Input:** Product URL or manual description
- **Platforms:** TikTok, Instagram Reels, YouTube Shorts, Facebook, landscape
- **Customization:** Edit text, music, pacing, and visual style after generation

### Lip Sync
**URL:** https://mobbi.ai/lip-sync
Sync audio to any face for realistic talking head videos. Supports any language, custom audio uploads, and built-in text-to-speech.

- **Languages:** Works with all languages (analyzes phonemes)
- **Audio input:** Upload audio files or use built-in text-to-speech
- **Use cases:** Video dubbing, talking avatars, educational content, personalized messages

---

## Image Generation Tools

### Text to Image
**URL:** https://mobbi.ai/text-to-image
Generate images from text descriptions. Supports photorealistic, artistic, anime, 3D render, and any other visual style.

- **Models:** Seedream 5.1 Lite (NEW — deep thinking + web search), Seedream 4.0, Seedream 4.5, Nano Banana 2 (4K, physics engine), Nano Banana Pro (best prompt accuracy), Flux Pro, Flux Ultra, GPT Image, Grok Imagine, Qwen Image, Ideogram V2, Recraft V3, SDXL, SD 3.5, and more
- **Resolutions:** Up to 4K depending on model
- **Styles:** Photorealistic, digital art, anime, oil painting, 3D renders, logos, product mockups

#### Seedream 5.1 Lite (Featured Model)
ByteDance's latest AI image model with unique capabilities:
- **Deep Thinking:** Multi-step reasoning architecture that analyzes prompt semantics, resolves ambiguities, and plans composition before rendering — 40-60% fewer regenerations needed
- **Real-Time Web Search:** Grounds generations in factual web knowledge for historically accurate, context-aware imagery
- **Precision Character Consistency:** Maintains identical facial features, proportions, and identity across multiple images with different outfits, environments, and poses
- **Resolution:** Up to 3K with PNG output support
- **Speed:** ~40 seconds per generation
- **Cost:** 4 credits per image on Mobbi
- **Aspect Ratios:** 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 21:9
- **Sequential Variant:** Batch generation of up to 15 consistent related images per request
- **Best For:** AI product photography, AI fashion photography, photorealistic images, character-consistent visual series, text rendering, editorial imagery

#### Nano Banana 2 (Featured Model)
Google's latest AI image model with five key capabilities:
- **Environment Control:** Consistent lighting, atmosphere, and scene composition across images
- **Advanced Physics Engine:** Realistic material simulation — liquid dynamics, metal reflections, fabric draping, particle effects
- **Prompt to Pixel:** Faithful rendering of complex multi-element prompts with minimal interpretation drift
- **Precise Text Rendering:** Accurate, legible text integrated naturally into scenes
- **Character Consistency:** Same subject maintains identity across multiple images with different outfits, poses, and environments
- **Resolution:** Up to 4K (1K, 2K, 4K options)
- **Speed:** ~20 seconds per generation
- **Cost:** 10 credits per image on Mobbi (same cost for 1K or 4K)
- **Aspect Ratios:** 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9 (10 options)
- **Best For:** Product visualization, fashion imagery, physics-heavy scenes, text-in-image, character-driven content, 4K output

### Image to Image
**URL:** https://mobbi.ai/image-to-image
Transform existing images with AI. Apply style transfers, modify elements, generate variations while preserving composition.

- **Transformations:** Style transfer, color changes, element modification, creative variations
- **Strength control:** Adjustable transformation intensity
- **Formats:** JPG, PNG, WebP input, up to 4K output

### Image Upscaler
**URL:** https://mobbi.ai/image-upscaler
Increase image resolution by 2x, 4x, or 8x. AI generates new detail pixels for sharp results even from low-resolution sources.

- **Scale factors:** 2x, 4x, 8x
- **Output:** Up to 4K resolution
- **Works on:** Old photos, screenshots, low-res images, compressed images

---

## 3D Generation Tools

### Text to 3D
**URL:** https://mobbi.ai/text-to-3d
Generate textured 3D models from text descriptions. AI creates geometry, textures, and materials in a single pass.

- **Models:** Meshy, Tripo, Rodin
- **Export formats:** GLB, OBJ, FBX
- **Use cases:** Games, AR/VR, 3D printing, product visualization
- **Generation time:** 1-3 minutes

### Image to 3D
**URL:** https://mobbi.ai/image-to-3d
Convert 2D images into full 3D models. The AI infers depth and hidden geometry from visible surfaces.

- **Input:** Any clear image (products, characters, objects work best)
- **Export formats:** GLB, OBJ, FBX
- **Output quality:** PBR textures, optimized polygon counts for real-time rendering

---

## Editing Tools

### Video Editor
**URL:** https://mobbi.ai/video-editor
AI-assisted video editing with timeline controls, auto-cut, transitions, captions, and effects.

- **Input formats:** MP4, MOV, AVI, WebM
- **Features:** Scene detection, auto-cropping, caption generation, transitions
- **Export:** MP4 (H.264) optimized for all social platforms

### Image Editor
**URL:** https://mobbi.ai/image-editor
AI photo editing with background removal, object removal, inpainting, style transfer, and generative fill.

- **Features:** Background removal, object removal, inpainting, color correction, upscaling
- **Selection:** Brush tool and click-to-select for precise editing
- **Output:** Full resolution PNG or JPG export

### Inpaint
**URL:** https://mobbi.ai/inpaint
Remove objects, fill missing areas, and replace elements using AI. Paint over any area and the AI fills it naturally.

- **Modes:** Object removal, generative fill (describe replacement), area repair
- **Quality:** Context-aware filling matches surrounding lighting, perspective, and style

### Face Swap
**URL:** https://mobbi.ai/face-swap (hub), https://mobbi.ai/video-face-swap, https://mobbi.ai/image-face-swap
Swap faces in photos and videos with realistic AI matching. Supports multiple face swaps per image/video.

- **Photo face swap:** Instant results, up to 4K resolution
- **Video face swap:** 1-3 minute processing, preserves expressions and movement
- **Multi-face:** Swap multiple faces in the same image or video

### Story Creator
**URL:** https://mobbi.ai/story
Generate visual stories from text descriptions with consistent characters, settings, and style across scenes.

- **Features:** Character consistency, multi-scene generation, style customization
- **Export:** Video slideshows or individual images
- **Genres:** Children's books, comics, storyboards, social media stories

---

## Video Effects

**URL:** https://mobbi.ai/video-effects

13+ viral AI video effects that generate short videos from a single photo:

| Effect | URL | Description |
|--------|-----|-------------|
| AI Kissing Generator | /video-effects/ai-kissing-generator | Romantic kiss videos with realistic expressions |
| AI Muscle Generator | /video-effects/ai-muscle-generator | Bodybuilder transformation effect |
| AI Dance Video | /video-effects/ai-dance-video-generator | Dance animation from photo |
| AI Beauty Filter | /video-effects/ai-beauty-filter-video | Beauty makeover and enhancement |
| AI Anime Filter | /video-effects/ai-anime-filter-video | Anime art style transformation |
| AI Couple Video | /video-effects/ai-couple-video-generator | Romantic couple interaction |
| AI Wedding Video | /video-effects/ai-wedding-video-maker | Wedding cinema effect |
| AI Red Carpet | /video-effects/ai-red-carpet-effect | Celebrity red carpet entrance |
| AI Camera Effects | /video-effects/ai-camera-effects | Cinematic camera movements |
| AI Gaming Effects | /video-effects/ai-gaming-video-effects | Gaming and pop culture effects |
| AI Pet Video | /video-effects/ai-pet-video-maker | Pet animation and interaction |
| AI Character Creator | /video-effects/ai-character-creator | Custom character generation |
| Album Cover Generator | /video-effects/album-cover-generator | Music album cover art |

---

## Supported Models

### Video Generation Models

| Model | Provider | Max Duration | Key Features |
|-------|----------|-------------|--------------|
| Sora 2 | OpenAI | 20s | Realistic world simulation |
| Sora 2 Pro | OpenAI | 20s | Higher quality Sora |
| Kling O1 | Kuaishou | 10s | Reference-based, up to 7 reference images |
| Kling v2.6 | Kuaishou | 10s | Latest Kling quality |
| Veo 3.1 | Google | 8s | Frame-to-frame control |
| Veo 3.1 Fast | Google | 8s | Faster Veo generation |
| Hailuo 2.3 | MiniMax | 6s | High quality video |
| Hailuo 2.3 Fast | MiniMax | 6s | Faster Hailuo generation |
| Seedance 1.5 Pro | ByteDance | 10s | Audio-visual generation with lip-sync |
| WAN 2.6 | Alibaba | 5s | Open-source model |
| Vidu Q2 | Shengshu | 8s | Quality-focused |

### AI Video Model Hubs

Each provider has a dedicated hub page on Mobbi listing all of its model versions:

<!-- AUTO:model-hubs:start -->
- **Google Veo** (Google DeepMind) — https://mobbi.ai/m/veo
  Models: Veo 3.1, Veo 3.1 Fast
- **Kling AI** (Kuaishou) — https://mobbi.ai/m/kling-ai
  Models: Kling O1, Kling v1, Kling v1.5, Kling v1.6, Kling v2 Master, Kling v2.1, Kling v2.1 Master, Kling v2.5 Turbo, Kling v2.6
- **Seedance** (ByteDance) — https://mobbi.ai/m/seedance
  Models: Seedance 1.5 Pro, Seedance 1.0 Pro Fast, Seedance 1.0 Pro, Seedance 1.0 Lite
- **OpenAI Sora** (OpenAI) — https://mobbi.ai/m/sora
  Models: Sora 2, Sora 2 Pro
- **Hailuo AI** (MiniMax) — https://mobbi.ai/m/hailuo-ai
  Models: Hailuo 2.3, Hailuo 2.3 Fast
- **Vidu** (Shengshu Technology) — https://mobbi.ai/m/vidu
  Models: Vidu Q2
- **Wan** (Alibaba) — https://mobbi.ai/m/wan
  Models: Wan 2.5, Wan 2.6
<!-- AUTO:model-hubs:end -->

### Image Generation Models

| Model | Provider | Key Features |
|-------|----------|--------------|
| Flux Pro | Black Forest Labs | High quality, general purpose |
| Flux Ultra | Black Forest Labs | Highest quality |
| GPT Image | OpenAI | Text understanding, instruction following |
| Nano Banana Pro | Custom | Ultra-high resolution up to 4K |
| Ideogram V2 | Ideogram | Text rendering in images, logos |
| Recraft V3 | Recraft | Illustrations, icons, vector graphics |

### 3D Generation Models

| Model | Provider | Export Formats | Best For |
|-------|----------|---------------|----------|
| Meshy | Meshy | GLB, FBX | General objects |
| Tripo | VAST | GLB | Image-to-3D |
| Rodin | Microsoft | GLB | Characters |

---

## Pricing & Credits

### Free Tier
- Daily free credits for all tools
- No credit card required
- No watermarks on output
- Commercial use allowed

### Premium Plans
- Additional monthly credits
- Priority processing queue
- Higher resolution limits
- API access via Renderful

### Credit Costs (approximate)
- Image generation: 1-10 credits per image
- Video generation: 10-50 credits per video
- 3D generation: 15-40 credits per model
- Upscaling: 2-5 credits per image/video
- Face swap: 5-15 credits per swap

---

## Languages & Availability

### Supported Languages (16)
English, Chinese (Simplified), Chinese (Traditional), Japanese, Korean, Spanish, Portuguese, French, German, Indonesian, Italian, Dutch, Turkish, Vietnamese, Arabic, Thai

### Platform Compatibility
- **Desktop:** Chrome, Firefox, Safari, Edge
- **Mobile:** Mobile web browsers (responsive design)
- **Accessibility:** Screen reader compatible, keyboard navigation

---

## Use Case Pages

| Use Case | URL |
|----------|-----|
| AI Video for YouTube | https://mobbi.ai/ai-video-for-youtube |
| AI Video for TikTok | https://mobbi.ai/ai-video-for-tiktok |
| AI Video for Instagram | https://mobbi.ai/ai-video-for-instagram |
| AI Video for E-Commerce | https://mobbi.ai/ai-video-for-ecommerce |
| AI Video for Real Estate | https://mobbi.ai/ai-video-for-real-estate |
| AI Video for Education | https://mobbi.ai/ai-video-for-education |
| Free AI Video Generator | https://mobbi.ai/free-ai-video-generator |

---

## Contact & Links

- **Website:** https://mobbi.ai
- **Pricing:** https://mobbi.ai/pricing
- **Help Center:** https://mobbi.ai/help
- **API (Renderful):** https://renderful.ai
- **Twitter:** https://twitter.com/mobbiAI
- **YouTube:** https://youtube.com/@mobbiAI

---
---

# Renderful AI - Complete API Reference for AI Agents

> AI-powered image, video, and 3D generation API with USDC cryptocurrency payments

## Table of Contents

1. [Overview](#overview)
2. [Agent Registration](#agent-registration)
3. [Payment System](#payment-system)
4. [API Endpoints](#api-endpoints)
5. [Generation Types](#generation-types)
6. [Models Reference](#models-reference)
7. [Pricing](#pricing)
8. [Webhooks](#webhooks)
9. [Error Handling](#error-handling)

---

## Overview

Renderful enables AI agents to generate visual content without requiring email or social authentication. Agents authenticate with `rf_` prefixed API keys and pay using USDC stablecoin on Base, Polygon, or Ethereum mainnet.

**Key Features:**
- No email/OAuth required - API key only authentication
- USDC cryptocurrency payments (no credit cards)
- x402 protocol support for inline payments
- Webhook notifications for async events
- 20+ image models, 5+ video models, 3+ 3D models

**Base URL:** `https://renderful.ai/api/v1`

---

## Agent Registration

### Register a New Agent

```http
POST /api/v1/agents/register
Content-Type: application/json

{
  "agent_name": "MyAIAgent",
  "webhook_url": "https://example.com/webhook"  // optional
}
```

**Response (201 Created):**
```json
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key": "rf_abc123def456ghi789jkl012mno345pqr678",
  "webhook_secret": "whsec_xyz789abc123",
  "deposit_addresses": {
    "base": "0x1234567890abcdef1234567890abcdef12345678",
    "polygon": "0x1234567890abcdef1234567890abcdef12345678",
    "ethereum": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "asset": "USDC",
  "balance": "0.00"
}
```

**Important:** The `api_key` is shown only once. Store it securely.

---

## Payment System

### Supported Payment Methods

1. **Prepaid Balance (Recommended)**
   - Deposit USDC to treasury address
   - Submit transaction hash via API
   - Balance credited after confirmations

2. **x402 Inline Payment**
   - Include `X-Payment-Proof: chain:txHash` header
   - Payment verified and credited per-request

### Deposit USDC

**Step 1:** Send USDC to the treasury address for your preferred chain:
- **Base:** Fastest, lowest fees (~$0.01)
- **Polygon:** Fast, low fees (~$0.05)
- **Ethereum:** Slower, higher fees (~$2-10)

**Step 2:** Submit the transaction hash:

```http
POST /api/v1/agents/deposit
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "chain": "base",
  "tx_hash": "0xabc123..."
}
```

**Response (200 OK):**
```json
{
  "success": true,
  "amount_usd": "10.00",
  "new_balance": "10.00",
  "payment_id": "pay_123456"
}
```

### Confirmation Requirements

| Chain    | Confirmations | Typical Wait Time |
|----------|---------------|-------------------|
| Base     | 3             | ~6 seconds        |
| Polygon  | 30            | ~1 minute         |
| Ethereum | 12            | ~3 minutes        |

### USDC Contract Addresses

| Chain    | USDC Address                               |
|----------|--------------------------------------------|
| Base     | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Polygon  | 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 |
| Ethereum | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |

---

## API Endpoints

### Check Balance

```http
GET /api/v1/agents/balance
Authorization: Bearer rf_your_api_key
```

**Response:**
```json
{
  "balance": "8.50",
  "deposit_addresses": {
    "base": "0x...",
    "polygon": "0x...",
    "ethereum": "0x..."
  },
  "asset": "USDC",
  "usage": {
    "total_requests": 150,
    "total_credits_used": 425,
    "total_usd_spent": "8.50"
  },
  "recent_transactions": [
    {
      "id": "pay_123",
      "type": "deposit",
      "amount_usd": "10.00",
      "chain": "base",
      "tx_hash": "0x...",
      "status": "confirmed",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

### Get Cost Quote

```http
POST /api/v1/agents/quote
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "text-to-video",
  "model": "hailuo-2.3",
  "duration": 6
}
```

**Response:**
```json
{
  "cost_credits": 20,
  "cost_usd": "0.40",
  "your_balance": "8.50",
  "sufficient_balance": true,
  "deposit_addresses": { ... }
}
```

### Update Webhook

```http
PATCH /api/v1/agents/webhook
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "webhook_url": "https://example.com/new-webhook"
}
```

---

## Generation Types

### Text-to-Image

```http
POST /api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "text-to-image",
  "model": "flux-1.1-pro",
  "prompt": "A futuristic cityscape at sunset, cyberpunk style",
  "negative_prompt": "blurry, low quality",
  "width": 1024,
  "height": 1024,
  "num_images": 1
}
```

### Image-to-Image

```http
POST /api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "image-to-image",
  "model": "flux-1.1-pro",
  "prompt": "Transform into oil painting style",
  "image_url": "https://example.com/input.jpg",
  "strength": 0.75
}
```

### Text-to-Video

```http
POST /api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "text-to-video",
  "model": "hailuo-2.3",
  "prompt": "A cat playing piano, cinematic lighting",
  "duration": 5,
  "aspect_ratio": "16:9"
}
```

### Image-to-Video

```http
POST /api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "image-to-video",
  "model": "kling-1.6",
  "image_url": "https://example.com/start-frame.jpg",
  "prompt": "The character starts walking forward",
  "duration": 5
}
```

### Text-to-3D

```http
POST /api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "text-to-3d",
  "model": "meshy",
  "prompt": "A medieval sword with ornate handle"
}
```

### Image-to-3D

```http
POST /api/v1/generations
Authorization: Bearer rf_your_api_key
Content-Type: application/json

{
  "type": "image-to-3d",
  "model": "tripo",
  "image_url": "https://example.com/object.jpg"
}
```

---

## Models Reference

### Image Models

| Model                        | Best For                                          | Cost (credits) |
|------------------------------|--------------------------------------------------|----------------|
| seedream-5.1-lite            | Deep thinking, web search, photorealism, 3K      | 4              |
| seedream-5.1-lite-sequential | Batch character-consistent series (up to 15)     | 4              |
| seedream-4.5                 | Enhanced quality and detail                       | 4              |
| seedream-4                   | Cohesive styles with prompts                      | 3              |
| nano-banana-2                | 4K, physics engine, fast (20s)                    | 10             |
| nano-banana-pro              | Best prompt-following accuracy                    | 18             |
| nano-banana                  | Character consistency, budget                     | 4              |
| gpt-image                    | Creative interpretation                           | 5              |
| grok-imagine                 | Fast creative generation                          | 3              |
| qwen-image                   | Complex text rendering                            | 4              |
| flux-1.1-pro                 | High quality, general use                         | 5              |
| flux-1.1-ultra               | Highest quality                                   | 10             |
| flux-1-pro                   | Quality, balanced                                 | 4              |
| flux-1-dev                   | Fast iterations                                   | 2              |
| ideogram-v2                  | Text rendering, logos                             | 4              |
| ideogram-v2-turbo            | Fast text rendering                               | 2              |
| recraft-v3                   | Illustrations, icons                              | 3              |
| recraft-v3-svg               | Vector graphics                                   | 4              |
| sdxl                         | General purpose                                   | 1              |
| sd3.5-large                  | Detailed images                                   | 3              |
| sd3.5-large-turbo            | Fast detailed images                              | 2              |

### Video Models

| Model       | Max Duration | Best For           | Cost (credits/sec) |
|-------------|--------------|--------------------|--------------------|
| hailuo-2.3  | 6s           | High quality       | 4                  |
| hailuo-2    | 6s           | Quality            | 3                  |
| kling-1.6   | 10s          | Motion, characters | 5                  |
| kling-1.5   | 10s          | Balanced           | 4                  |
| luma        | 5s           | Creative           | 3                  |
| runway-gen3 | 10s          | Cinematic          | 6                  |
| pika        | 4s           | Stylized           | 2                  |

### 3D Models

| Model  | Output Format | Best For          | Cost (credits) |
|--------|---------------|-------------------|----------------|
| meshy  | GLB, FBX      | General objects   | 20             |
| tripo  | GLB           | From images       | 25             |
| rodin  | GLB           | Characters        | 30             |

---

## Pricing

### Credit System

- **1 credit = $0.02 USD**
- Balance stored in USD cents for precision
- Deducted after successful generation

### Cost Calculation

```
Total Cost = Base Cost x Multipliers

Multipliers:
- Resolution: 1x (1024px), 1.5x (1536px), 2x (2048px)
- Duration: Linear for video (cost x seconds)
- Batch: Linear for multiple images
```

### Example Costs

| Generation Type        | Model        | Parameters      | Credits | USD    |
|-----------------------|--------------|-----------------|---------|--------|
| Text-to-Image         | flux-1.1-pro | 1024x1024       | 5       | $0.10  |
| Text-to-Image         | flux-1.1-ultra| 1024x1024      | 10      | $0.20  |
| Text-to-Video         | hailuo-2.3   | 5 seconds       | 20      | $0.40  |
| Text-to-Video         | kling-1.6    | 10 seconds      | 50      | $1.00  |
| Text-to-3D            | meshy        | Standard        | 20      | $0.40  |

---

## Webhooks

### Supported Events

| Event                | Description                           |
|---------------------|---------------------------------------|
| balance.low         | Balance dropped below $1.00           |
| payment.received    | USDC deposit confirmed                |
| generation.complete | Generation finished (success/failure) |

### Webhook Payload

```json
{
  "event": "generation.complete",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "generation_id": "gen_abc123",
    "status": "completed",
    "type": "text-to-image",
    "output_url": "https://..."
  }
}
```

### Signature Verification

Webhooks include an HMAC-SHA256 signature in `X-Webhook-Signature` header:

```
X-Webhook-Signature: sha256=abc123...
```

Verify by computing:
```
HMAC-SHA256(webhook_secret, request_body)
```

---

## Error Handling

### HTTP Status Codes

| Code | Meaning               | Action                          |
|------|-----------------------|---------------------------------|
| 200  | Success               | Process response                |
| 201  | Created               | Resource created successfully   |
| 400  | Bad Request           | Fix request parameters          |
| 401  | Unauthorized          | Check API key                   |
| 402  | Payment Required      | Deposit more USDC               |
| 404  | Not Found             | Check endpoint/resource         |
| 429  | Rate Limited          | Wait and retry                  |
| 500  | Server Error          | Retry with backoff              |

### 402 Payment Required Response

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance. Required: $0.40, Available: $0.10",
    "type": "payment_error"
  },
  "required_amount": "0.40",
  "current_balance": "0.10",
  "deposit_addresses": {
    "base": "0x...",
    "polygon": "0x...",
    "ethereum": "0x..."
  },
  "asset": "USDC"
}
```

### Error Response Format

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "type": "error_type"
  }
}
```

---

## Quick Start Example (Python)

```python
import requests

BASE_URL = "https://renderful.ai/api/v1"

# 1. Register agent
response = requests.post(f"{BASE_URL}/agents/register", json={
    "agent_name": "MyAgent"
})
data = response.json()
api_key = data["api_key"]
deposit_address = data["deposit_addresses"]["base"]

print(f"API Key: {api_key}")
print(f"Deposit USDC to: {deposit_address}")

# 2. After depositing USDC, submit tx hash
headers = {"Authorization": f"Bearer {api_key}"}
requests.post(f"{BASE_URL}/agents/deposit", headers=headers, json={
    "chain": "base",
    "tx_hash": "0x..."
})

# 3. Check balance
balance = requests.get(f"{BASE_URL}/agents/balance", headers=headers).json()
print(f"Balance: ${balance['balance']}")

# 4. Generate image
result = requests.post(f"{BASE_URL}/generations", headers=headers, json={
    "type": "text-to-image",
    "model": "flux-1.1-pro",
    "prompt": "A beautiful mountain landscape"
})
print(f"Image URL: {result.json()['output_url']}")
```

---

## Support

- **Documentation:** https://api.renderful.ai/docs
- **Email:** hello@renderful.ai
- **Website:** https://renderful.ai