# Flux 2 Dev + LoRA API Documentation

> LLM-optimized documentation for Flux 2 Dev + LoRA. Copy into your AI assistant for integration help.

## Overview

**Model ID:** `flux-2-dev-lora`
**Type:** Image Generation
**Credit Cost:** 1 credits per image (by resolution: 0.5 MP: 1, 1 MP: 1, 2 MP: 1.5, 4 MP: 2)

Flux 2 Dev with your own FLUX.2 [dev] LoRAs and up to 4 reference images

## Endpoint

```
POST https://pixeldojo.ai/api/v1/models/flux-2-dev-lora/run
```

## Authentication

All requests require an API key in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

Get your API key: https://pixeldojo.ai/api-platform/api-keys

## Input Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Text description of the image to generate |
| `input_images` | array | No | - | Optional array of reference image URLs (up to 10). When supplied, the request becomes a multi-image edit and the model composes / restyles based on the references plus the prompt. Every variant is edit-capable; the per-variant ceiling applies (Flex 10, Pro/Max 8, Dev and Dev + LoRA 4, Klein and Klein 9B + LoRA 5) and extras are dropped. Flex adds 2 credits, Max 1 credit and Dev + LoRA 0.25 credits for each reference image sent, on top of the output price; on those three, each reference is downscaled to at most 1 megapixel (aspect ratio kept) before it is sent, and one we cannot read is refused and refunded. Omit for plain text-to-image. |
| `aspect_ratio` | enum | No | 1:1 | Output aspect ratio. Pass `match_input_image` to inherit the aspect of the first input image (multi-image edits only). Pass `custom` with `width` and `height` (each rounded to a multiple of 32) for a free-form size; on Flex and Max that size is billed as the smallest resolution tier holding it (1 MP = 1024 x 1024) and can be at most 4 MP (2048 x 2048). (Options: 1:1, 16:9, 9:16, 3:2, 2:3...) |
| `resolution` | enum | No | 1 MP | Output resolution in megapixels (Options: 0.5 MP, 1 MP, 2 MP, 4 MP) |
| `safety_tolerance` | integer | No | 5 | Content filter strictness (1=strict, 5=permissive) (min: 1, max: 5) |
| `prompt_upsampling` | boolean | No | false | Provider-side LLM prompt rewriting. Off by default so your exact prompt is followed. Turn on to auto-enhance short prompts. |
| `seed` | integer | No | - | Random seed for reproducibility |
| `output_format` | enum | No | png | Image output format (Options: png, jpg, webp) |
| `loras` | array | No | - | Custom LoRA weights, applied by the flux-2-lora (Klein 9B LoRAs) and flux-2-dev-lora (FLUX.2 [dev] LoRAs) variants only and ignored by the others. Each entry is an object: {"url": "<safetensors URL>", "scale": 1.0}. Up to 3 stack, extras are dropped, and scale defaults to 1.0. The URL must be a LoRA you trained here or a Hugging Face / Civitai link. On flux-2-dev-lora, the first request with a LoRA it has not seen yet answers that the LoRA is being prepared (a few minutes; the credits are refunded); retry after that. |

## Supported Aspect Ratios

- `1:1`
- `16:9`
- `9:16`
- `3:2`
- `2:3`
- `4:5`
- `5:4`
- `3:4`
- `4:3`

## Capabilities

- Text to Image
- Image to Image
- LoRA Support

## Quick Start

### 1. Submit a Job

```bash
curl -X POST "https://pixeldojo.ai/api/v1/models/flux-2-dev-lora/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cinematic portrait in rim light",
    "resolution": "1 MP"
  }'
```

**Response:**
```json
{
  "jobId": "job_abc123...",
  "status": "pending",
  "statusUrl": "https://pixeldojo.ai/api/v1/jobs/job_abc123",
  "creditCost": 1,
  "creditsRemaining": 95
}
```

### 2. Poll for Results

```bash
curl "https://pixeldojo.ai/api/v1/jobs/job_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Completed Response:**
```json
{
  "jobId": "job_abc123...",
  "status": "completed",
  "output": {
    "images": ["https://temp.pixeldojo.ai/..."]
  },
  "creditCost": 1
}
```

## Python Example

```python
import requests
import time

API_KEY = "YOUR_API_KEY"

# Submit job
response = requests.post(
    "https://pixeldojo.ai/api/v1/models/flux-2-dev-lora/run",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "a cinematic portrait in rim light",
        "resolution": "1 MP"
    }
)

job = response.json()
job_id = job["jobId"]

# Poll for completion
while True:
    status_response = requests.get(
        f"https://pixeldojo.ai/api/v1/jobs/{'{job_id}'}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    status = status_response.json()
    
    if status["status"] == "completed":
        print("Output:", status["output"])
        break
    elif status["status"] == "failed":
        print("Error:", status.get("error"))
        break
    
    time.sleep(2)
```

## JavaScript Example

```javascript
const API_KEY = 'YOUR_API_KEY';

// Submit job
const submitResponse = await fetch('https://pixeldojo.ai/api/v1/models/flux-2-dev-lora/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "prompt": "a cinematic portrait in rim light",
    "resolution": "1 MP"
  })
});

const job = await submitResponse.json();

// Poll for completion
const pollForResult = async (jobId) => {
  while (true) {
    const statusResponse = await fetch(`https://pixeldojo.ai/api/v1/jobs/${jobId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });
    const status = await statusResponse.json();
    
    if (status.status === 'completed') return status.output;
    if (status.status === 'failed') throw new Error(status.error);
    
    await new Promise(r => setTimeout(r, 2000));
  }
};

const output = await pollForResult(job.jobId);
console.log('Output:', output);
```

## Use Saved Characters (@Name)

Write `@Name` in the prompt to use a character, product, outfit, location, prop or style saved in the account's Character Studio, for example `"@Mara on a beach at sunset"`. Its photos are added to `images` automatically, after any images you send yourself, so your own image numbering is unchanged. List saved names with `GET /api/v1/characters` and save new ones with `POST /api/v1/characters`. An `@word` that names nothing saved stays plain text.

## Error Codes

| Code | Status | Description |
|------|--------|-------------|
| `unauthorized` | 401 | Invalid or missing API key |
| `insufficient_credits` | 402 | Not enough credits |
| `invalid_request` | 400 | Invalid parameters |
| `model_not_found` | 404 | Model ID not found |
| `internal_error` | 500 | Server error |

## Links

- **Full Documentation:** https://pixeldojo.ai/api-platform/flux-2-dev-lora
- **API Keys:** https://pixeldojo.ai/api-platform/api-keys
- **Buy Credits:** https://pixeldojo.ai/api-platform/buy-credits
- **All Models:** https://pixeldojo.ai/api/v1/models
- **OpenAPI Spec:** https://pixeldojo.ai/api/openapi