# PixelDojo API (Async Jobs)

> Optimized for LLM consumption. Copy into your AI assistant.
> This document is dynamically generated from live model data.

## Overview
PixelDojo provides an async job-based API for AI image and video generation.

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

### Core Endpoints
- `POST /api/v1/models/{apiId}/run` — Submit a generation job
- `GET /api/v1/jobs/{jobId}` — Poll job status and outputs
- `GET /api/v1/models` — List available models (with credit costs)
- `GET /api/v1/models/{apiId}` — Model details + input parameters

## Authentication
All requests require an API key:
```
Authorization: Bearer YOUR_API_KEY
```

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

## Requirements
- API key
- Sufficient credits (per-image for image models, per-second for video models)

## Image Models (32 available)

### Flux Dev (`flux-dev`)
High-quality development model with configurable steps, guidance, and LoRA support.
- Cost: 1 credit(s)
- Features: LoRA

### Flux Krea Dev (`flux-krea-dev`)
Photorealistic generation that avoids the oversaturated AI look. LoRA compatible.
- Cost: 1 credit(s)
- Features: LoRA

### Flux 1.1 Pro (`flux-1.1-pro`)
Latest pro model with enhanced quality and strong prompt adherence.
- Cost: 1 credit(s)

### Flux 1.1 Pro Ultra (`flux-1.1-pro-ultra`)
Highest quality Flux model with raw mode for natural-looking images.
- Cost: 1.5 credit(s)

### Flux Kontext Pro (`flux-kontext-pro`)
Advanced model with state-of-the-art performance for both generation and editing.
- Cost: 1 credit(s)
- Features: Editing

### Flux Kontext Max (`flux-kontext-max`)
Premium model with maximum performance and improved typography for generation and editing.
- Cost: 2 credit(s)
- Features: Editing

### Flux 2 Flex (`flux-2-flex`)
Max-quality with up to 10 reference images
- Cost: 1.5 credit(s) (by resolution: 0.5 MP=1, 1 MP=1.5, 2 MP=3, 4 MP=5)
- Features: LoRA, Editing

### Flux 2 Klein 4B (`flux-2-klein-4b`)
Very fast generation and editing with up to 5 reference images
- Cost: 0.1 credit(s)
- Features: LoRA, Editing

### Flux 2 Klein 9B (`flux-2-klein-9b`)
4-step distilled FLUX.2 [klein] foundation model for flexible control
- Cost: 0.5 credit(s)
- Features: LoRA, Editing

### Flux 2 Pro (`flux-2-pro`)
High-quality with up to 8 reference images
- Cost: 1.5 credit(s) (by resolution: 0.5 MP=1, 1 MP=1.5, 2 MP=2, 4 MP=2)
- Features: LoRA, Editing

### Flux 2 Max (`flux-2-max`)
The highest fidelity image model from Black Forest Labs
- Cost: 2 credit(s) (by resolution: 0.5 MP=1, 1 MP=2, 2 MP=3, 4 MP=4)
- Features: LoRA, Editing

### Flux 2 Dev (`flux-2-dev`)
Fast quality with up to 4 reference images
- Cost: 1 credit(s)
- Features: LoRA, Editing

### Seedream 4.5 (`seedream-4`)
ByteDance Seedream 4.5 - New-generation image creation with superior aesthetics, text rendering, and up to 4K resolution
- Cost: 1 credit(s)
- Features: Editing

### Seedream 5 Lite (`seedream-5-lite`)
ByteDance Seedream 5.0 Lite - fast, high-quality image generation and editing with strong aesthetics and text rendering
- Cost: 1 credit(s)
- Features: Editing

### Pony Realism (`ponyxl-ponyrealism-v23`)
Pony Realism - Stylized anime generation
- Cost: 1 credit(s)
- Features: LoRA

### Pony NAI (`ponyxl-tponynai3-v7`)
Pony NAI - Stylized anime generation
- Cost: 1 credit(s)
- Features: LoRA

### Wai ANI (`ponyxl-waianinsfwponyxl-v140`)
Wai ANI - Stylized anime generation
- Cost: 1 credit(s)
- Features: LoRA

### QWEN Image Plus (`qwen-image-plus`)
Fast generation with excellent quality
- Cost: 1 credit(s)
- Features: LoRA, Editing

### QWEN Image Max (`qwen-image-max`)
Highest quality output
- Cost: 2 credit(s)
- Features: LoRA, Editing

### QWEN Image 2.0 (`qwen-image-2.0`)
Fast, balanced image generation and editing
- Cost: 1 credit(s)
- Features: Editing

### QWEN Image 2.0 Pro (`qwen-image-2.0-pro`)
Enhanced text rendering, realistic textures, and semantic adherence
- Cost: 2 credit(s)
- Features: Editing

### WAN 2.2 Image (`wan-image`)
Fast cinematic image generation (3-6 seconds) with up to 4MP output and optional LoRA support
- Cost: 1 credit(s)
- Features: LoRA

### WAN 2.6 Image (`wan-2.6-image`)
Alibaba WAN 2.6 high-quality AI image generation with prompt enhancement and up to 2MP output
- Cost: 1 credit(s)
- Features: Editing

### Z Image Turbo (`z-image-turbo`)
Super fast 6B parameter photorealistic image generation with excellent text rendering and LoRA support
- Cost: 0.5 credit(s)
- Features: LoRA

### P-Image (`p-image`)
Sub-second text-to-image generation with exceptional text rendering and prompt adherence
- Cost: 1 credit(s)
- Features: Editing

### ImagineArt 1.5 Pro (`imagineart`)
Advanced text-to-image model generating ultra-high-fidelity 4K visuals with lifelike realism and refined aesthetics
- Cost: 1.5 credit(s)

### Google Gemini Flash (`gemini-flash`)
Fast generation with Gemini 2.5 Flash
- Cost: 1 credit(s)
- Features: Editing

### Google Nano Banana Pro (`nano-banana-pro`)
SOTA with accurate typography and reasoning
- Cost: 3 credit(s) (by resolution: 1K=3, 2K=3, 4K=6)
- Features: Editing

### Google Nano Banana 2 (`nano-banana-2`)
Next-generation SOTA model with stronger consistency
- Cost: 3 credit(s) (by resolution: 1K=2, 2K=3, 4K=4)
- Features: Editing

### Kling Image V3 (`kling-image`)
Kling Image V3 text-to-image generation with optional image edits and flexible aspect ratios
- Cost: 1 credit(s)
- Features: Editing

### xAI Image (`xai-image`)
xAI Grok Imagine Image via Replicate for text-to-image and single-image edits
- Cost: 1 credit(s)
- Features: Editing

### Dreamina 3.1 (`dreamina`)
ByteDance 4MP cinematic image generation with enhanced quality, precise style control, and commercial design optimization
- Cost: 1 credit(s)

## Video Models (4 available)

### WAN 2.6 Flash (`wan-2.6-flash`)
Fast and affordable image-to-video
- Cost: 1 credits/sec (by resolution: 720p=1, 1080p=1.5 /sec)
- Features: Audio

### WAN 2.2 Plus (`wan-2.2-plus`)
Official Alibaba model with 1080p support
- Cost: 10 credit(s)
- Features: LoRA

### Seedance 1.5 (`seedance-1.5`)
ByteDance Seedance 1.5 video generation with native audio, dance motion, 480p/720p resolution, and up to 12 seconds duration
- Cost: 1.5 credits/sec
- Features: Audio

### xAI Video (`xai-video`)
xAI video generation via Replicate with text-to-video and image-to-video support
- Cost: 2 credits/sec

> Full list with parameters: `GET /api/v1/models`

## Response Format

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

### Completed Response
```json
{
  "jobId": "job_abc123",
  "status": "completed",
  "output": {
    "images": ["https://temp.pixeldojo.ai/...png"]
  },
  "creditCost": 1,
  "expiresAt": "2025-01-23T12:00:00Z"
}
```

## Error Codes

| Code | Status | Description |
|------|--------|-------------|
| `unauthorized` | 401 | Missing or invalid API key |
| `invalid_json` | 400 | Invalid JSON in request body |
| `validation_error` | 400 | Input validation failed |
| `not_found` | 404 | Model or job not found |
| `insufficient_credits` | 402 | Insufficient credits |
| `credit_error` | 500 | Failed to deduct credits |
| `submission_failed` | 500 | Failed to submit job |
| `expired` | 410 | Job has expired |
| `rate_limit_exceeded` | 429 | Rate limit exceeded |
| `internal_error` | 500 | Internal server error |

## Rate Limits
60 requests per minute across all endpoints.

## Examples

### cURL
```bash
# Submit a job
curl -X POST "https://pixeldojo.ai/api/v1/models/flux-1.1-pro/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset", "aspect_ratio": "1:1", "webhook_url": "https://example.com/webhook"}'

# Poll for results
curl "https://pixeldojo.ai/api/v1/jobs/job_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# List recent jobs
curl "https://pixeldojo.ai/api/v1/jobs?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Replay a terminal webhook
curl -X POST "https://pixeldojo.ai/api/v1/jobs/job_abc123/webhook" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Python
```python
import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://pixeldojo.ai/api/v1"

model_schema = requests.get(
  f"{BASE_URL}/models/flux-1.1-pro/schema"
).json()

submit_response = requests.post(
  f"{BASE_URL}/models/flux-1.1-pro/run",
  headers={
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
  },
  json={"prompt": "A sunset", "aspect_ratio": "1:1", "webhook_url": "https://example.com/webhook"},
)
job = submit_response.json()

while True:
  status = requests.get(
    job["statusUrl"],
    headers={"Authorization": f"Bearer {API_KEY}"}
  ).json()
  if status["status"] in {"completed", "failed"}:
    print(status)
    break
  time.sleep(2)
```

### JavaScript
```javascript
const schema = await fetch("https://pixeldojo.ai/api/v1/models/flux-1.1-pro/schema");
const requestSchema = await schema.json();

const submit = await fetch("https://pixeldojo.ai/api/v1/models/flux-1.1-pro/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A sunset",
    aspect_ratio: "1:1",
    webhook_url: "https://example.com/webhook"
  })
});

const job = await submit.json();
let result;

do {
  const status = await fetch(job.statusUrl, {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  });
  result = await status.json();
  if (result.status === "pending" || result.status === "processing") {
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
} while (result.status === "pending" || result.status === "processing");

console.log(requestSchema.schema, result.assets, result.webhook);
```

## Best Practices
1. Store API keys securely - never in client-side code
2. Poll job status with exponential backoff (start at 2s, max 30s)
3. Download outputs promptly (24h expiry)
4. Use seeds for reproducibility
5. Use webhook_url instead of polling for production workloads

## Links
- API Platform: https://pixeldojo.ai/api-platform
- API Keys: https://pixeldojo.ai/api-platform/api-keys
- Documentation: https://pixeldojo.ai/api-platform/documentation
- OpenAPI Spec: https://pixeldojo.ai/api/openapi
- llms.txt: https://pixeldojo.ai/llms.txt