Guida all'SDK

The official @rendra/client TypeScript SDK wraps the REST API with a fully typed, ergonomic interface.

Installation

npm install @rendra/client

The SDK ships with TypeScript declarations — no @types package needed.

Quick Start

import { createClient } from '@rendra/client';

const rendra = createClient({
  apiKey: process.env.RENDRA_API_KEY!,
});

// Generate and wait for completion in one call
const image = await rendra.generateAndWait({
  prompt: 'A modern tech blog header with gradient background and bold white title text',
  width: 1200,
  height: 630,
});

console.log(image.url);
// → https://cdn.rendra.dev/gen_abc123.png

Configuration

const rendra = createClient({
  apiKey: process.env.RENDRA_API_KEY!,  // required
  baseUrl: 'https://rendra.alphabros.eu/api/v1', // optional, default shown
  timeout: 30_000,                        // optional, ms (default: 30s)
});

Methods

• generate(options: GenerateOptions): Promise<Generation>
  Submits a generation request and returns immediately with a pending generation object. Use generateAndWait() if you need the final URL.
• generateAndWait(options: GenerateOptions, pollOptions?: PollOptions): Promise<CompletedGeneration>
  Submits a generation and polls until status === "completed". Returns the completed generation with a populated url. Throws if generation fails or times out.
• getGeneration(id: string): Promise<Generation>
  Fetches the current status of a generation by ID. Equivalent to GET /api/v1/generate/:id.
• getDashboard(): Promise<Dashboard>
  Returns usage statistics and plan information for the authenticated user.
• getHistory(options?: HistoryOptions): Promise<Generation[]>
  Returns a paginated list of past generations. Accepts optional limit and offset parameters.

TypeScript Types

interface GenerateOptions {
  prompt: string;
  width?: number;   // default: 1200
  height?: number;  // default: 630
  format?: 'png' | 'jpeg';  // default: 'png'
}

interface Generation {
  id: string;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  url: string | null;
  width: number;
  height: number;
  prompt: string;
  created_at: string;
}

interface CompletedGeneration extends Generation {
  status: 'completed';
  url: string;  // guaranteed non-null
}

interface PollOptions {
  intervalMs?: number;  // default: 1000
  timeoutMs?: number;   // default: 60_000
}

interface Dashboard {
  plan: 'free' | 'pro';
  usage: {
    current_period: number;
    limit: number;
    resets_at: string;
  };
  total_generations: number;
}

interface HistoryOptions {
  limit?: number;   // default: 20
  offset?: number;  // default: 0
}

Framework Examples

Next.js — Route Handler

// app/api/og/route.ts
import { createClient } from '@rendra/client';
import { NextRequest, NextResponse } from 'next/server';

const rendra = createClient({ apiKey: process.env.RENDRA_API_KEY! });

export async function POST(req: NextRequest) {
  const { title, description } = await req.json();

  const image = await rendra.generateAndWait({
    prompt: `Blog OG image: "${title}" — ${description}. Clean, modern design with purple gradient.`,
    width: 1200,
    height: 630,
  });

  return NextResponse.json({ url: image.url });
}

Node.js — Express Middleware

import express from 'express';
import { createClient } from '@rendra/client';

const rendra = createClient({ apiKey: process.env.RENDRA_API_KEY! });
const app = express();

app.post('/generate-og', express.json(), async (req, res) => {
  const image = await rendra.generateAndWait({
    prompt: req.body.prompt,
    width: req.body.width ?? 1200,
    height: req.body.height ?? 630,
  });
  res.json({ url: image.url });
});