# Generate Images

AI-powered image generation with FLUX and SDXL models

## Navigation

**Getting Started:** [All You Need](/index.md) | [Getting Started](/introduction.md) | [How Sapiom Works](/how-it-works.md) | [Quick Start](/quick-start.md) | [Using Services](/using-services.md) | [For AI Tools](/for-agents.md)  
**Capabilities:** [Overview](/capabilities.md) | [Verify Users](/capabilities/verify.md) | [Search the Web](/capabilities/search.md) | [AI Model Access](/capabilities/ai-models.md) | **Generate Images** | [Audio Services](/capabilities/audio.md) | [Browser Automation](/capabilities/browser.md)  
**Integration / Agent Frameworks:** [Overview](/integration/agent-frameworks.md) | [LangChain](/integration/agent-frameworks/langchain.md) | [LangChain Classic](/integration/agent-frameworks/langchain-classic.md)  
**Integration / HTTP Clients:** [Overview](/integration/http-clients.md) | [Axios](/integration/http-clients/axios.md) | [Fetch](/integration/http-clients/fetch.md) | [Node.js HTTP](/integration/http-clients/node-http.md)  
**Governance:** [Overview](/governance.md) | [Setting Up Rules](/governance/rules.md) | [Agents & Identity](/governance/agents.md) | [Activity](/governance/activity.md)  
**Reference / API Reference:** [Introduction](/api-reference/introduction.md)  
**Reference / API Reference / Endpoints:** [Agents Endpoints](/api-reference/endpoints/agents.md) | [Get agent by ID](/api-reference/endpoints/agents/v1-agents-by-id-get.md) | [Update agent](/api-reference/endpoints/agents/v1-agents-by-id-patch.md) | [List all agents](/api-reference/endpoints/agents/v1-agents-get.md) | [Create a new agent](/api-reference/endpoints/agents/v1-agents-post.md) | [API Endpoints](/api-reference/endpoints.md) | [Get Sapiom payment JWKS](/api-reference/endpoints/other/.well-known-sapiom-jwks.json-get.md) | [Analytics Endpoints](/api-reference/endpoints/other.md) | [Get analytics chart](/api-reference/endpoints/other/v1-analytics-chart-get.md) | [Get analytics leaderboards](/api-reference/endpoints/other/v1-analytics-leaderboards-get.md) | [Get analytics summary](/api-reference/endpoints/other/v1-analytics-summary-get.md) | [Rules Endpoints](/api-reference/endpoints/rules.md) | [Get rule by ID](/api-reference/endpoints/rules/v1-spending-rules-by-id-get.md) | [Update a rule](/api-reference/endpoints/rules/v1-spending-rules-by-ruleId-put.md) | [List all rules](/api-reference/endpoints/rules/v1-spending-rules-get.md) | [Create a new rule](/api-reference/endpoints/rules/v1-spending-rules-post.md) | [Transactions Endpoints](/api-reference/endpoints/transactions.md) | [Complete a transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-complete-post.md) | [List transaction costs](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-get.md) | [Add cost to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-post.md) | [Add facts to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-facts-post.md) | [Get transaction details](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-get.md) | [Reauthorize a transaction with x402 payment data](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-reauthorize-post.md) | [List transactions](/api-reference/endpoints/transactions/v1-transactions-get.md) | [Create a new transaction](/api-reference/endpoints/transactions/v1-transactions-post.md) | [Verification Endpoints](/api-reference/endpoints/verification.md) | [Check verification code](/api-reference/endpoints/verification/v1-services-verify-check-post.md) | [Send verification code](/api-reference/endpoints/verification/v1-services-verify-send-post.md)  
**Reference / SDK Reference:** [@sapiom/axios](/reference/sdk/axios.md) | [@sapiom/fetch](/reference/sdk/fetch.md) | [SDK Reference](/reference/sdk.md) | [@sapiom/langchain-classic](/reference/sdk/langchain-classic.md) | [@sapiom/langchain](/reference/sdk/langchain.md) | [@sapiom/node-http](/reference/sdk/node-http.md)  
**Reference:** [Concepts](/reference/concepts.md)

---

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

```typescript

// Create a Sapiom-tracked fetch function
const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  agentName: "my-agent",
});

// Generate image with Fal.ai - SDK handles payment/auth automatically
const response = await sapiomFetch(
  "https://fal.services.sapiom.ai/v1/run/fal-ai/flux/dev",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: "A serene mountain landscape at sunset",
      image_size: "landscape_4_3",
    }),
  }
);

const data = await response.json();
console.log("Generated image:", 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.services.sapiom.ai/v1/run/{model}`

Generate one or more images from a text prompt. The model is specified in the URL path.

**Supported models:** `fal-ai/flux/dev`, `fal-ai/flux/schnell`, `fal-ai/flux-pro`, `fal-ai/stable-diffusion-xl`

#### Request

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Text description of the image to generate |
| `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",
  "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.services.sapiom.ai/v1/run/fal-ai/flux/dev/image-to-image`

Transform an existing image using img2img techniques. The model path can vary — use any Fal img2img model.

#### 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.services.sapiom.ai/v1/run/fal-ai/topaz/upscale/image`

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

**Endpoint:** `POST https://fal.services.sapiom.ai/v1/price/run/{model}`

Get the estimated cost before making a request. Use the same model path as the main endpoint (e.g., `v1/price/run/fal-ai/flux/dev`).

```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

```typescript

const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  agentName: "my-agent",
});

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

async function generateProductImage(description: string) {
  // Generate a product visualization
  const response = await sapiomFetch(`${baseUrl}/run/fal-ai/flux/dev`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: `Professional product photo: ${description}, studio lighting, white background`,
      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 sapiomFetch(`${baseUrl}/run/fal-ai/flux/dev/image-to-image`, {
    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