# Images and Vision

div
strong
🔨 In Development
 — This section is still being developed and may change.


Freddy provides powerful image generation and manipulation capabilities through integration with leading AI providers including OpenAI DALL-E and ClipDrop by Stability AI.

## Overview

The Image APIs enable you to:

- **Generate images** from text descriptions
- **Upscale images** to higher resolutions
- **Remove backgrounds** automatically
- **Replace backgrounds** with AI-generated scenes
- **Cleanup images** by removing unwanted objects


**Note:** Vision capabilities (understanding and analyzing images) are planned for future release.

## Supported operations

### Image generation

Create original images from text prompts using advanced AI models.

**Models:**

- **DALL-E 3** (OpenAI) - Highest quality, best prompt understanding
- **DALL-E 2** (OpenAI) - Faster, lower cost
- **ClipDrop Text-to-Image** - Fast and cost-effective


**Use cases:**

- Marketing and advertising visuals
- Product mockups and concepts
- Social media content
- Illustration and art
- Rapid prototyping


[Learn more →](/docs/api-reference/images/generate)

### Image upscaling

Enhance image resolution up to 4096x4096 pixels while preserving quality.

**Models:**

- **ClipDrop Upscale** - AI-powered resolution enhancement


**Use cases:**

- Prepare images for print
- Enhance low-resolution photos
- Scale for large displays
- Improve thumbnail quality


[Learn more →](/docs/api-reference/images/upscale)

### Background removal

Automatically isolate subjects by removing backgrounds, producing transparent PNGs.

**Models:**

- **ClipDrop Remove Background** - Automatic segmentation


**Use cases:**

- E-commerce product photos
- Profile pictures
- Marketing materials
- Graphic design projects


[Learn more →](/docs/api-reference/images/remove-background)

### Background replacement

Replace image backgrounds with AI-generated scenes based on text descriptions.

**Models:**

- **ClipDrop Replace Background** - AI scene generation


**Use cases:**

- Product photography in various settings
- Portrait photography with custom backdrops
- Real estate staging
- Marketing content variations


[Learn more →](/docs/api-reference/images/replace-background)

### Image cleanup

Remove unwanted objects from images using mask-based selection.

**Models:**

- **ClipDrop Cleanup** - AI-powered object removal


**Use cases:**

- Remove photobombers
- Clean product images
- Erase watermarks
- Professional photo retouching


[Learn more →](/docs/api-reference/images/cleanup)

## Providers

### OpenAI (DALL-E)

OpenAI's DALL-E models excel at understanding complex prompts and generating high-quality, creative images.

**Strengths:**

- Superior prompt interpretation
- Highest image quality (DALL-E 3)
- Style consistency
- Safety filtering


**Models:**

- `dall-e-3` - Latest, highest quality
- `dall-e-3-hd` - HD quality for large formats
- `dall-e-2` - Faster, lower cost


### ClipDrop (Stability AI)

ClipDrop specializes in practical image manipulation with fast processing and competitive pricing.

**Strengths:**

- Fast processing
- Cost-effective
- Specialized tools
- Reliable results


**Models:**

- `clipdrop-text-to-image` - Image generation
- `clipdrop-upscale` - Resolution enhancement
- `clipdrop-cleanup` - Object removal
- `clipdrop-remove-background` - Background removal
- `clipdrop-replace-background` - Background replacement


## Billing

Image operations are billed in **Synapses**, Freddy's unified billing unit.

### Synapse costs

| Operation | Model | Synapses per operation |
|  --- | --- | --- |
| **Generate** | DALL-E 2 | 25,000 |
| **Generate** | DALL-E 3 | 50,000 |
| **Generate** | DALL-E 3 HD | 100,000 |
| **Generate** | ClipDrop Text-to-Image | 12,500 |
| **Upscale** | ClipDrop Upscale | 12,500 |
| **Cleanup** | ClipDrop Cleanup | 12,500 |
| **Remove BG** | ClipDrop Remove Background | 12,500 |
| **Replace BG** | ClipDrop Replace Background | 12,500 |


### Pricing tiers

Your organization's pricing tier affects the final cost:

- **Standard tier**: No discount (0%)
- **POC tier**: 50% discount
- **Custom tier**: Negotiated rates


Synapses are converted to CHF at a rate of **0.00072 CHF per 1,000 synapses**, then your tier discount is applied.

### Cost examples

**DALL-E 3 image (Standard tier):**

- 50,000 synapses × 0.00072 CHF/1K = 0.036 CHF per image


**ClipDrop operations (Standard tier):**

- 12,500 synapses × 0.00072 CHF/1K = 0.009 CHF per operation


**DALL-E 3 with POC tier (50% discount):**

- Base: 50,000 synapses × 0.00072 = 0.036 CHF
- After discount: 0.036 × 0.5 = 0.018 CHF per image


Monitor usage in the [Aitronos Hub](https://freddy-hub.aitronos.com/freddy/api).

## Best practices

### Prompt engineering

**Be specific:**

- ✅ "A modern minimalist living room with large windows, natural light, white walls, and a grey sofa"
- ❌ "A room"


**Include style details:**

- Art style: "digital art", "oil painting", "3D render"
- Mood: "warm", "dramatic", "peaceful"
- Lighting: "golden hour", "studio lighting", "natural light"


**Use descriptive language:**

- Colors, textures, materials
- Composition and framing
- Atmosphere and mood


### Model selection

**For highest quality:**

- Use DALL-E 3 for complex scenes
- Use DALL-E 3 HD for large format images


**For cost efficiency:**

- Use DALL-E 2 for simpler needs
- Use ClipDrop for straightforward generation
- Use ClipDrop tools for manipulations


**For speed:**

- ClipDrop models process faster
- DALL-E 2 faster than DALL-E 3


### Image size selection

**Square (1024x1024):**

- Social media posts
- Avatars and icons
- Product photos


**Landscape (1792x1024):**

- Website banners
- Presentations
- Desktop wallpapers


**Portrait (1024x1792):**

- Mobile wallpapers
- Posters
- Story formats


### File handling

**Supported formats:**

- PNG (recommended for transparency)
- JPEG (smaller file size)
- WebP (modern format)


**Size limits:**

- Maximum upload: 4MB per file
- Recommended resolution: 1024px minimum


**Response formats:**

- `b64_json` - Direct base64 encoding (default)
- `url` - Temporary hosted URL (1 hour expiry)


## Code examples

### Generate image with Python


```python
import requests
import base64
from pathlib import Path

api_key = "your_api_key_here"
org_id = "org_abc123"

response = requests.post(
    "https://api.freddy.aitronos.com/v1/images/generate",
    headers={"api-key": api_key},
    json={
        "organizationId": org_id,
        "prompt": "A serene mountain landscape at sunset",
        "model": "dall-e-3",
        "size": "1024x1024"
    }
)

data = response.json()
image_b64 = data["data"][0]["b64_json"]

# Save image
image_bytes = base64.b64decode(image_b64)
Path("output.png").write_bytes(image_bytes)
```

### Remove background with Node.js


```javascript
const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

const apiKey = 'your_api_key_here';
const orgId = 'org_abc123';

async function removeBackground(imagePath) {
  const form = new FormData();
  form.append('organizationId', orgId);
  form.append('image', fs.createReadStream(imagePath));
  
  const response = await fetch(
    'https://api.freddy.aitronos.com/v1/images/remove-background',
    {
      method: 'POST',
      headers: { 'api-key': apiKey },
      body: form
    }
  );
  
  const data = await response.json();
  const imageBuffer = Buffer.from(data.data[0].b64_json, 'base64');
  fs.writeFileSync('output.png', imageBuffer);
}

removeBackground('input.jpg');
```

### Upscale image with cURL


```bash
curl https://api.freddy.aitronos.com/v1/images/upscale \
  -H "api-key: $FREDDY_API_KEY" \
  -F "organizationId=org_abc123" \
  -F "image=@photo.jpg" \
  -F "targetWidth=2048" \
  -F "targetHeight=2048"
```

## Rate limits

Image operations are subject to rate limiting:

- **Burst**: 50 requests per minute
- **Sustained**: 10 requests per second
- **Concurrent**: 5 simultaneous operations


Exceeding limits returns `429 Too Many Requests`.

## Error handling

Common error codes:

| Code | Status | Description |
|  --- | --- | --- |
| `invalid_request_error` | 400 | Invalid parameters or format |
| `file_too_large` | 413 | File exceeds 4MB limit |
| `insufficient_credits` | 402 | Not enough Synapses |
| `rate_limit_exceeded` | 429 | Too many requests |
| `internal_error` | 500 | Service error |


**Example error response:**


```json
{
  "error": {
    "message": "File too large: 5242880 bytes. Maximum: 4194304 bytes (4MB)",
    "code": "file_too_large"
  }
}
```

## Security and compliance

- API keys should be stored securely (environment variables)
- Generated images follow provider content policies
- Safety filters prevent inappropriate content
- All requests are logged for audit purposes


## Future capabilities

**Vision (planned):**

- Image analysis and understanding
- Object detection
- OCR (text extraction)
- Image classification
- Content moderation


Stay updated via [Aitronos documentation](https://docs.aitronos.com).

## Related resources

- [API Reference: Images](/docs/api-reference/images/generate)
- [Image Object](/docs/api-reference/images/objects/image-object)
- [Authentication](/docs/api-reference/authentication)
- [Aitronos Hub](https://freddy-hub.aitronos.com)