@pixeldojo/sdk

TypeScript SDK for the PixelDojo image and video generation API.

Install

npm install @pixeldojo/sdk

Quick Start

import { PixelDojoClient } from '@pixeldojo/sdk';

const pd = new PixelDojoClient({ apiKey: 'pd_your_api_key' });

// Generate an image and wait for the result
const job = await pd.generate('flux-1.1-pro', {
  prompt: 'A fantasy castle on a cliff at sunset',
  aspect_ratio: '16:9',
});

console.log(job.assets[0].url);

Usage

List available models

const { models } = await pd.listModels();
const imageModels = await pd.listModels({ modality: 'image' });

Get model schema

const schema = await pd.getModelSchema('flux-1.1-pro');
console.log(schema.schema); // JSON Schema for the request body

Submit a job (async)

const submitted = await pd.run('flux-1.1-pro', {
  prompt: 'A sunset over the ocean',
  aspect_ratio: '1:1',
  webhook_url: 'https://example.com/webhook',
});

console.log(submitted.jobId);     // "job_abc123"
console.log(submitted.statusUrl); // poll URL

Poll for results

const job = await pd.getJob('job_abc123');

if (job.status === 'completed') {
  console.log(job.output?.images);
  console.log(job.assets);
}

Generate and wait (convenience)

const job = await pd.generate('wan-2.6-video', {
  prompt: 'Drone flight through coastal cliffs',
  duration: 6,
  aspect_ratio: '16:9',
}, {
  intervalMs: 3000,
  timeoutMs: 120_000,
  onStatusChange: (j) => console.log(`Status: ${j.status}`),
});

List recent jobs

const { jobs } = await pd.listJobs({ limit: 10, status: 'completed' });

Webhooks

// Check webhook delivery state
const state = await pd.getWebhookState('job_abc123');

// Replay a webhook for a completed/failed job
const replay = await pd.replayWebhook('job_abc123');

Error Handling

import {
  PixelDojoClient,
  InsufficientCreditsError,
  NotFoundError,
  TimeoutError,
} from '@pixeldojo/sdk';

try {
  const job = await pd.generate('flux-1.1-pro', { prompt: 'Hello' });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    console.log(`Need ${err.required} credits, have ${err.available}`);
  } else if (err instanceof NotFoundError) {
    console.log('Model not found');
  } else if (err instanceof TimeoutError) {
    console.log(`Job ${err.jobId} timed out — you can still poll manually`);
  }
}

Configuration

const pd = new PixelDojoClient({
  apiKey: 'pd_your_api_key',
  baseUrl: 'https://pixeldojo.ai',  // default
  fetch: customFetchFn,              // optional, for testing or custom runtimes
});

API Reference

| Method | Description | |--------|-------------| | listModels(options?) | List all available models | | getModel(apiId) | Get model details including schema | | getModelSchema(apiId) | Get the JSON Schema for a model's request body | | run(apiId, input) | Submit a generation job (returns immediately) | | getJob(jobId) | Poll a job's status and results | | listJobs(options?) | List recent jobs for your API key | | getWebhookState(jobId) | Inspect webhook delivery status | | replayWebhook(jobId) | Replay webhook for completed/failed jobs | | generate(apiId, input, options?) | Submit + poll until complete |

License

MIT