# Generate Images

AI-powered image generation with FLUX and SDXL models

> **Coming Soon:** This service is not yet available. Documentation is provided for preview purposes.

Generate images from text prompts, transform existing images, or upscale low-resolution images — all through a single API with no account setup required.

## Quick Example

**Axios:**
```typescript
    import { withSapiom } from "@sapiom/axios";
    import axios from "axios";

    const client = withSapiom(axios.create(), {
      apiKey: process.env.SAPIOM_API_KEY,
    });

    const { data } = await client.post(
      "https://fal-ai.services.sapiom.ai/v1/generate",
      {
        prompt: "A cyberpunk cityscape at sunset with neon signs",
        model: "flux-dev",
        image_size: "landscape_16_9",
      }
    );

    console.log("Image URL:", data.images[0].url);
    ```
  
**Fetch:**
```typescript
    import { createFetch } from "@sapiom/fetch";

    const fetch = createFetch({
      apiKey: process.env.SAPIOM_API_KEY,
    });

    const response = await fetch(
      "https://fal-ai.services.sapiom.ai/v1/generate",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          prompt: "A cyberpunk cityscape at sunset with neon signs",
          model: "flux-dev",
          image_size: "landscape_16_9",
        }),
      }
    );

    const data = await response.json();
    console.log("Image URL:", data.images[0].url);
    ```
  
## How It Works

Sapiom routes image generation requests to [FAL](https://fal.ai), which provides access to state-of-the-art image generation models including FLUX and SDXL. The SDK handles payment negotiation automatically — you pay per megapixel based on the model and image size.

The service supports three operations:

1. **Generate** — Create images from text prompts
2. **Transform** — Modify existing images with img2img
3. **Upscale** — Increase image resolution

## Provider

Powered by [FAL](https://fal.ai). FAL provides fast, scalable inference for generative AI models with optimized GPU infrastructure.

## API Reference

### Generate Image

**Endpoint:** `POST https://fal-ai.services.sapiom.ai/v1/generate`

Generate one or more images from a text prompt.

#### Request

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate |
| `model` | string | No | `flux-dev`, `flux-schnell`, `flux-pro`, or `sdxl` (default: `flux-dev`) |
| `image_size` | string | No | Size preset (default: `landscape_4_3`) |
| `num_images` | number | No | Number of images to generate, 1-4 (default: 1) |
| `num_inference_steps` | number | No | Quality steps, 1-100 (default: 28) |
| `guidance_scale` | number | No | Prompt adherence (default: 3.5) |
| `output_format` | string | No | `jpeg` or `png` (default: `jpeg`) |
| `seed` | number | No | Seed for reproducible generation |

**Image size presets:**

| Preset | Dimensions |
|--------|------------|
| `square_hd` | 1024 × 1024 |
| `square` | 512 × 512 |
| `portrait_4_3` | 768 × 1024 |
| `portrait_16_9` | 576 × 1024 |
| `landscape_4_3` | 1024 × 768 |
| `landscape_16_9` | 1024 × 576 |

```json
{
  "prompt": "A serene mountain lake at dawn with mist",
  "model": "flux-dev",
  "image_size": "landscape_16_9",
  "num_images": 1
}
```

#### Response

```json
{
  "images": [
    {
      "url": "https://fal.media/files/abc123.jpg",
      "width": 1024,
      "height": 576,
      "content_type": "image/jpeg"
    }
  ],
  "seed": 42,
  "prompt": "A serene mountain lake at dawn with mist"
}
```

### Transform Image

**Endpoint:** `POST https://fal-ai.services.sapiom.ai/v1/transform`

Transform an existing image using img2img techniques.

#### Request

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image_url` | string | Yes | URL of the input image |
| `prompt` | string | Yes | Description of the desired transformation |
| `image_size` | string | No | Output size preset (default: `landscape_4_3`) |
| `strength` | number | No | Transformation strength, 0.0-1.0 (default: 0.75) |
| `num_inference_steps` | number | No | Quality steps, 1-100 (default: 28) |
| `num_images` | number | No | Number of outputs, 1-4 (default: 1) |
| `output_format` | string | No | `jpeg` or `png` (default: `jpeg`) |
| `seed` | number | No | Seed for reproducible generation |

```json
{
  "image_url": "https://example.com/photo.jpg",
  "prompt": "Transform into a watercolor painting style",
  "strength": 0.75
}
```

#### Response

```json
{
  "images": [
    {
      "url": "https://fal.media/files/xyz789.jpg",
      "width": 1024,
      "height": 768,
      "content_type": "image/jpeg"
    }
  ]
}
```

### Upscale Image

**Endpoint:** `POST https://fal-ai.services.sapiom.ai/v1/upscale`

Increase image resolution while preserving quality.

#### Request

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `image_url` | string | Yes | URL of the image to upscale |
| `model` | string | No | Upscaling model (default: `topaz`) |
| `scale` | number | No | Scale factor: `2` or `4` (default: 2) |
| `output_format` | string | No | `jpeg` or `png` (default: `jpeg`) |

```json
{
  "image_url": "https://example.com/small-image.jpg",
  "scale": 4
}
```

#### Response

```json
{
  "image": {
    "url": "https://fal.media/files/upscaled.jpg",
    "width": 4096,
    "height": 3072,
    "content_type": "image/jpeg"
  }
}
```

### Price Estimation

**Endpoints:**
- `POST https://fal-ai.services.sapiom.ai/v1/generate/price`
- `POST https://fal-ai.services.sapiom.ai/v1/transform/price`
- `POST https://fal-ai.services.sapiom.ai/v1/upscale/price`

Get the estimated cost before making a request. Accepts the same parameters as the main endpoint.

```json
{
  "price": "$0.012",
  "currency": "USD"
}
```

### Error Codes

| Code | Description |
|------|-------------|
| 400 | Invalid request — check parameters and image URL |
| 402 | Payment required — ensure you're using the Sapiom SDK |
| 404 | Model not found |
| 413 | Image too large for processing |
| 429 | Rate limit exceeded |

## Complete Example

**Axios:**
```typescript
    import { withSapiom } from "@sapiom/axios";
    import axios from "axios";

    const client = withSapiom(axios.create(), {
      apiKey: process.env.SAPIOM_API_KEY,
    });

    const baseUrl = "https://fal-ai.services.sapiom.ai/v1";

    async function generateProductImage(description: string) {
      // Generate a product visualization
      const { data } = await client.post(`${baseUrl}/generate`, {
        prompt: `Professional product photo: ${description}, studio lighting, white background`,
        model: "flux-dev",
        image_size: "square_hd",
        num_images: 1,
        guidance_scale: 4.0,
      });

      return data.images[0].url;
    }

    async function createVariation(imageUrl: string, style: string) {
      // Transform an existing image
      const { data } = await client.post(`${baseUrl}/transform`, {
        image_url: imageUrl,
        prompt: `Render in ${style} style`,
        strength: 0.6,
      });

      return data.images[0].url;
    }

    // Usage
    const productImage = await generateProductImage("minimalist desk lamp");
    console.log("Generated:", productImage);

    const artVariation = await createVariation(productImage, "pop art");
    console.log("Variation:", artVariation);
    ```
  
**Fetch:**
```typescript
    import { createFetch } from "@sapiom/fetch";

    const fetch = createFetch({
      apiKey: process.env.SAPIOM_API_KEY,
    });

    const baseUrl = "https://fal-ai.services.sapiom.ai/v1";

    async function generateProductImage(description: string) {
      // Generate a product visualization
      const response = await fetch(`${baseUrl}/generate`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          prompt: `Professional product photo: ${description}, studio lighting, white background`,
          model: "flux-dev",
          image_size: "square_hd",
          num_images: 1,
          guidance_scale: 4.0,
        }),
      });

      const data = await response.json();
      return data.images[0].url;
    }

    async function createVariation(imageUrl: string, style: string) {
      // Transform an existing image
      const response = await fetch(`${baseUrl}/transform`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          image_url: imageUrl,
          prompt: `Render in ${style} style`,
          strength: 0.6,
        }),
      });

      const data = await response.json();
      return data.images[0].url;
    }

    // Usage
    const productImage = await generateProductImage("minimalist desk lamp");
    console.log("Generated:", productImage);

    const artVariation = await createVariation(productImage, "pop art");
    console.log("Variation:", artVariation);
    ```
  
## Pricing

Pricing is based on megapixels (MP) — the total pixels in the output image divided by 1,000,000.

| Model | Price per MP |
|-------|--------------|
| flux-schnell | $0.004 |
| flux-dev | $0.015 |
| flux-pro | $0.04 |
| sdxl | $0.007 |

| Operation | Price per MP |
|-----------|--------------|
| Transform (img2img) | $0.045 |
| Upscale | $0.03 |

**Example costs (landscape_4_3 = 0.79 MP):**
- flux-schnell: ~$0.003
- flux-dev: ~$0.012
- flux-pro: ~$0.032

> **Using Python?:** See [Service Proxy](/md/service-proxy.md) for REST API access without the Node.js SDK.