@imaige/sdk

Official TypeScript SDK for the Imaige API — image, video, and text generation.

Installation

npm install @imaige/sdk
# or
pnpm add @imaige/sdk

Authentication

All requests require an imk_… API key. Provide it via:

• IMAIGE_API_KEY environment variable, or
• apiKey option in the ImaigeClient constructor.

Quick start

import { ImaigeClient } from '@imaige/sdk';

const client = new ImaigeClient({ apiKey: process.env.IMAIGE_API_KEY });

// Text-to-image (async enqueue → poll to completion)
const result = await client.generateImageAndWait({
  prompt: 'A serene alpine landscape at sunset',
  model: 'flux-dev',
});
console.log(result.mediaUrls); // ['https://api.imaige.io/media/media/…']

// Non-blocking: get a job handle, then poll manually
const handle = await client.generateImage({ prompt: '…', model: '…' });
console.log(handle.jobId); // 'job_abc123…'
const row = await client.getJob(handle.jobId);
console.log(row.status); // 'pending' | 'processing' | 'complete' | 'error'

CLI

npx imaige --help

# Generate an image and wait for the result
npx imaige generate --prompt "A sunset" --model flux-dev --wait

# List your recent jobs
npx imaige list-jobs --limit 10

# Start the MCP server over stdio (for AI agents)
npx imaige mcp

Set IMAIGE_API_KEY in your environment or pass --api-key imk_… globally.

Available methods

| Method | Route | Description | |---|---|---| | generateImage(req) | POST /v1/images/generate | Text-to-image | | transformImage(req) | POST /v1/images/transform | Image-to-image / inpaint | | upscaleImage(req) | POST /v1/images/upscale | AI upscale | | removeBackground(req) | POST /v1/images/remove-background | Background removal | | svgTrace(req) | POST /v1/images/svg-trace | Raster → SVG vectorization | | analyzeImage(req) | POST /v1/images/analyze | VLM scene analysis | | animateVideo(req) | POST /v1/videos/animate | Image-to-video | | generateText(req) | POST /v1/text/generate | Text generation | | getJob(jobId) | GET /v1/jobs/{id} | Fetch job row | | listJobs(filter?) | GET /v1/jobs | List jobs (paginated) | | waitForJob(jobId) | polls GET /v1/jobs/{id} | Block until terminal | | streamJob(jobId) | GET /v1/jobs/{id}/events | SSE progress stream | | uploadMedia(file, type) | POST /v1/media/upload | Upload a file | | listModels() | GET /models | Available models | | checkQuota(mode?) | GET /jobs/quota | Quota info | | constructPrompt(req) | POST /prompt/construct | Build a model prompt | | listKeys() | GET /v1/keys | List API keys | | createKey(params?) | POST /v1/keys | Create an API key | | deleteKey(keyId) | DELETE /v1/keys/{keyId} | Delete an API key |

Every generation method also has an *AndWait() variant that polls to completion.

Streaming

for await (const event of client.streamJob(jobId)) {
  console.log(event.progress, event.status);
  if (event.terminal) {
    console.log(event.mediaUrls);
    break;
  }
}

MCP server

The SDK ships a stdio MCP server exposing 12 tools (same surface as the HTTP API):

# Launch manually
IMAIGE_API_KEY=imk_… imaige mcp

# Or embed in your own server
import { buildMcpServer } from '@imaige/sdk';
import { ImaigeClient } from '@imaige/sdk';
const server = buildMcpServer(new ImaigeClient({ apiKey: '…' }));

Configuration

const client = new ImaigeClient({
  apiKey: 'imk_…',
  baseUrl: 'https://api.imaige.io',  // default
  requestTimeoutMs: 60_000,          // per-request timeout (default 60 s)
  pollIntervalMs: 2_000,             // waitForJob poll interval (default 2 s)
  waitTimeoutMs: 600_000,            // waitForJob max wait (default 10 min)
});

License

MIT — Copyright (c) 2024 Black Leaf Digital