PixelDojo API Reference

Overview

Base URL

https://pixeldojo.ai/api/v1

Auth

Authorization: Bearer YOUR_API_KEY

Format

JSON request/response

Pattern

Async jobs: discover schema, submit via POST, poll via GET, replay webhooks when needed

Models

144 enabled (82 image, 58 video, 4 audio/3D)

Get API Key

pixeldojo.ai/api-platform/api-keys

Authentication

All API requests require an API key sent as a Bearer token in the Authorization header. API keys are available to signed-in accounts, and usage is billed against prepaid credits.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create API keys at /api-platform/api-keys. API access does not require a subscription. Buy credits at /api-platform/buy-credits.

Endpoints

curl "https://pixeldojo.ai/api/v1/models?detailed=true"

{
  "models": [
    {
      "apiId": "flux-1.1-pro",
      "name": "Flux 1.1 Pro",
      "description": "High-quality image generation with strong prompt adherence.",
      "modality": "image",
      "creditCost": {
        "default": 1,
        "type": "fixed",
        "amount": 1
      }
    }
  ],
  "total": 42,
  "imageCount": 25,
  "videoCount": 17
}

curl "https://pixeldojo.ai/api/v1/models/flux-1.1-pro"

{
  "apiId": "flux-1.1-pro",
  "name": "Flux 1.1 Pro",
  "modality": "image",
  "requestSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "description": "Text prompt"
      }
    }
  },
  "endpoints": {
    "run": "/api/v1/models/flux-1.1-pro/run",
    "schema": "/api/v1/models/flux-1.1-pro/schema"
  }
}

curl "https://pixeldojo.ai/api/v1/models/flux-1.1-pro/schema"

{
  "apiId": "flux-1.1-pro",
  "name": "Flux 1.1 Pro",
  "modality": "image",
  "schema": {
    "title": "Flux 1.1 ProRequest",
    "type": "object",
    "additionalProperties": false,
    "required": [
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "description": "Text prompt"
      }
    }
  }
}

curl -X POST "https://pixeldojo.ai/api/v1/models/flux-1.1-pro/run" -H "Authorization: Bearer YOUR_API_KEY" -d '{"prompt": "A sunset", "aspect_ratio": "1:1"}'

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

curl "https://pixeldojo.ai/api/v1/jobs?limit=10&status=completed" -H "Authorization: Bearer YOUR_API_KEY"

{
  "jobs": [
    {
      "jobId": "job_abc123",
      "apiId": "flux-1.1-pro",
      "status": "completed",
      "creditCost": 1,
      "refunded": false,
      "assets": [
        {
          "assetId": "job_abc123:image:0",
          "kind": "image",
          "url": "https://temp.pixeldojo.ai/...png",
          "apiId": "flux-1.1-pro",
          "jobId": "job_abc123",
          "expiresAt": "2026-03-17T12:00:00.000Z"
        }
      ],
      "webhook": {
        "configured": true,
        "delivered": true,
        "attempts": 1
      },
      "createdAt": "2026-03-17T11:59:00.000Z",
      "updatedAt": "2026-03-17T12:00:00.000Z",
      "expiresAt": "2026-03-18T12:00:00.000Z"
    }
  ],
  "total": 1,
  "filters": {
    "limit": 10,
    "status": "completed"
  }
}

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

{
  "jobId": "job_abc123",
  "apiId": "flux-1.1-pro",
  "status": "completed",
  "creditCost": 1,
  "refunded": false,
  "output": {
    "images": [
      "https://temp.pixeldojo.ai/...png"
    ]
  },
  "assets": [
    {
      "assetId": "job_abc123:image:0",
      "kind": "image",
      "url": "https://temp.pixeldojo.ai/...png",
      "apiId": "flux-1.1-pro",
      "jobId": "job_abc123",
      "expiresAt": "2025-01-23T12:00:00Z"
    }
  ],
  "webhook": {
    "configured": true,
    "url": "https://example.com/webhook",
    "delivered": true,
    "attempts": 1
  },
  "createdAt": "2025-01-23T11:58:00Z",
  "updatedAt": "2025-01-23T12:00:00Z",
  "expiresAt": "2025-01-23T12:00:00Z"
}

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

{
  "jobId": "job_abc123",
  "apiId": "flux-1.1-pro",
  "status": "completed",
  "webhook": {
    "configured": true,
    "url": "https://example.com/webhook",
    "delivered": true,
    "attempts": 1
  }
}

curl -X POST "https://pixeldojo.ai/api/v1/jobs/job_abc123/webhook" -H "Authorization: Bearer YOUR_API_KEY"

{
  "replayed": true,
  "job": {
    "jobId": "job_abc123",
    "apiId": "flux-1.1-pro",
    "status": "completed",
    "webhook": {
      "configured": true,
      "delivered": true,
      "attempts": 2
    }
  }
}

curl -X POST "https://pixeldojo.ai/api/v1/upload" -H "Authorization: Bearer YOUR_API_KEY" -F "file=@/path/to/photo.png"

{
  "url": "https://temp.pixeldojo.ai/pixeldojotemp/mcp-uploads/user_abc/1717000000-x9p2k1.png",
  "expiresInHours": 24
}

curl "https://pixeldojo.ai/api/v1/library?q=hero%20shot&modality=image" -H "Authorization: Bearer YOUR_API_KEY"

{
  "items": [
    {
      "url": "https://cdn.pixeldojo.ai/pixeldojo/generated-images/1717-abc.png",
      "prompt": "steel bottle hero shot",
      "model": "seedream-4",
      "modality": "image",
      "source": "saved",
      "createdAt": "2026-07-08T18:00:00.000Z"
    }
  ],
  "count": 1,
  "expiredCount": 0
}

curl -X POST "https://pixeldojo.ai/api/v1/media/save" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"url":"https://temp.pixeldojo.ai/pixeldojotemp/1717-abc.png","prompt":"hero shot","tool_name":"flux-1.1-pro"}'

{
  "saved": true,
  "id": "1717000000-x9p2k1",
  "url": "https://cdn.pixeldojo.ai/pixeldojo/generated-images/1717000000-x9p2k1.png",
  "kind": "image"
}

curl "https://pixeldojo.ai/api/v1/workflows" -H "Authorization: Bearer YOUR_API_KEY"

{
  "workflows": [
    {
      "name": "launch-pack",
      "description": "hero + variants",
      "steps": [
        {
          "skill": "pixeldojo:generate",
          "args": {
            "prompt": "{{input.subject}} hero shot"
          }
        }
      ],
      "runs": 3,
      "updatedAt": "2026-07-08T18:00:00.000Z"
    }
  ]
}

claude mcp add --transport http pixeldojo https://pixeldojo.ai/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "serverInfo": {
      "name": "pixeldojo",
      "version": "0.5.0"
    },
    "capabilities": {
      "tools": {}
    }
  }
}

curl "https://pixeldojo.ai/api/v1/credits" -H "Authorization: Bearer YOUR_API_KEY"

{
  "credits": 99
}

Available Models (144)

Also available programmatically: GET https://pixeldojo.ai/api/v1/models. This list updates automatically when models are enabled or disabled.

For any single model, fetch GET https://pixeldojo.ai/api/v1/models/{apiId}/schema to retrieve the canonical request schema before submitting a job.

Image Models (82)

Video Models (58)

Audio & 3D Models (4)

Response Format

Submit Response (202)

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

Completed Response (200)

{
  "jobId": "job_abc123",
  "apiId": "flux-1.1-pro",
  "status": "completed",
  "output": {
    "images": [
      "https://temp.pixeldojo.ai/pixeldojotemp/...png"
    ]
  },
  "assets": [
    {
      "assetId": "job_abc123:image:0",
      "kind": "image",
      "url": "https://temp.pixeldojo.ai/pixeldojotemp/...png"
    }
  ],
  "webhook": {
    "configured": true,
    "delivered": true,
    "attempts": 1
  },
  "creditCost": 1,
  "refunded": false,
  "createdAt": "2026-03-17T11:59:00Z",
  "updatedAt": "2026-03-17T12:00:00Z",
  "expiresAt": "2026-02-07T12:00:00Z"
}

Job Statuses

• pending — Job queued, not yet started
• processing — Generation in progress
• completed — Outputs ready to download
• failed — Generation failed (see error field)

Control Plane

PixelDojo exposes agent-friendly control-plane routes for inspecting request schemas, listing recent jobs, and replaying terminal webhooks.

• GET https://pixeldojo.ai/api/v1/models/{apiId}/schema — canonical JSON Schema for one model
• GET https://pixeldojo.ai/api/v1/jobs — recent jobs for the authenticated API key owner
• GET https://pixeldojo.ai/api/v1/jobs/{jobId} — full job state including asset references and webhook delivery info
• GET https://pixeldojo.ai/api/v1/jobs/{jobId}/webhook — inspect webhook delivery state
• POST https://pixeldojo.ai/api/v1/jobs/{jobId}/webhook — replay the terminal webhook for completed or failed jobs

Installable Surfaces

PixelDojo is designed to be consumable by different kinds of agent runtimes. Use the surface that best matches your stack:

• OpenAPI + schema endpoints: generate clients and inspect per-model request shapes
• LLM docs: /llm.txt, /llms.txt, and ai-plugin.json support agent discovery and prompt-time reasoning
• Dashboard docs: OpenAPI info and LLM info document the recommended SDK, CLI, and MCP-style integration patterns

Error Codes

Code Examples

cURL

# 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

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

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);

TypeScript

interface JobSubmitResponse {
  jobId: string;
  status: "pending" | "processing";
  statusUrl: string;
  creditCost: number;
  creditsRemaining: number;
  expiresAt: string;
}

interface JobAsset {
  assetId: string;
  kind: "image" | "video";
  url: string;
}

interface JobResult {
  jobId: string;
  apiId: string;
  status: "pending" | "processing" | "completed" | "failed";
  assets: JobAsset[];
  webhook: { configured: boolean; delivered: boolean; attempts: number };
  output?: { images?: string[]; video?: string };
  error?: string;
}

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: JobSubmitResponse = await submit.json();
const resultResponse = await fetch(job.statusUrl, {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const result: JobResult = await resultResponse.json();

if (result.status === "completed") {
  console.log(result.assets);
}

Rate Limits

60 requests per minute across all endpoints.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1738800000

Best Practices

1. Store API keys securely — never in client-side code or public repos
2. Fetch /models/{apiId}/schema before generating dynamic payloads for a model
3. Poll job status with exponential backoff (start at 2s, max 30s)
4. Use asset references from job responses to track outputs across retries and orchestration steps
5. Download outputs promptly — generated content expires after 24 hours
6. Use seed for reproducible results across identical prompts
7. Use webhook_url instead of polling for production workloads
8. Handle rate limits gracefully with retry logic