Gamma Performance Tuning
Overview
Optimize Gamma API integration performance. Gamma's generate-poll-retrieve pattern means most latency is in generation time (10-60s), not API call overhead. Optimize by: reducing poll overhead, parallelizing batch operations, caching results, and choosing the right generation parameters.
Prerequisites
- Working Gamma integration (see
gamma-sdk-patterns)
- Understanding of async patterns
- Redis or in-memory cache (recommended)
Performance Characteristics
| Operation | Typical Latency | Notes |
|---|
POST /generations | 200-500ms | Just starts the generation |
GET /generations/{id} (poll) | 100-300ms | Per poll request |
| Full generation (poll to completion) | 10-60s | Depends on content + cards |
GET /themes | 100-200ms | Cacheable |
GET /folders | 100-200ms | Cacheable |
Instructions
Step 1: Optimize Poll Strategy
export async function smartPoll(
gamma: GammaClient,
generationId: string,
opts = { maxTimeMs: 180000 }
): Promise<GenerateResult> {
const deadline = Date.now() + opts.maxTimeMs;
let interval = 2000;
while (Date.now() < deadline) {
const result = await gamma.poll(generationId);
if (result.status === "completed") return result;
if (result.status === "failed") throw new Error("Generation failed");
await new Promise((r) => setTimeout(r, interval));
interval = Math.min(interval * 1.5, 10000);
}
throw new Error(`Poll timeout after ${opts.maxTimeMs}ms`);
}
Step 2: Cache Static Data
import NodeCache from "node-cache";
const cache = new NodeCache({ stdTTL: 3600 });
export async function getCachedThemes(gamma: GammaClient) {
const key = "gamma:themes";
const cached = cache.get(key);
if (cached) return cached;
const themes = await gamma.listThemes();
cache.set(key, themes);
return themes;
}
export async function getCachedFolders(gamma: GammaClient) {
const key = "gamma:folders";
const cached = cache.get(key);
if (cached) return cached;
const folders = await gamma.listFolders();
cache.set(key, folders);
return folders;
}
export async () {
cache.(, result, );
}
Step 3: Parallel Batch Generation
import pLimit from "p-limit";
const limit = pLimit(3);
export async function batchGenerate(
gamma: GammaClient,
requests: Array<{ content: string; exportAs?: string }>
): Promise<Array<{ index: number; result?: GenerateResult; error?: string }>> {
const results = await Promise.allSettled(
requests.map((req, index) =>
limit(async () => {
const { generationId } = await gamma.generate({
content: req.content,
outputFormat: "presentation",
exportAs: req.exportAs,
});
const result = await smartPoll(gamma, generationId);
return { index, result };
})
)
);
return results.( {
(r. === ) r.;
{ : i, : (r. ). };
});
}
Step 4: Reduce Generation Time
await gamma.generate({
content: "Comprehensive 20-card guide to machine learning...",
outputFormat: "presentation",
textAmount: "extensive",
});
await gamma.generate({
content: "5-card overview of ML basics: supervised, unsupervised, reinforcement, deep learning, applications",
outputFormat: "presentation",
textAmount: "brief",
});
await gamma.generate({
content: "Your pre-written slide content here...",
outputFormat: "presentation",
textMode: "preserve",
});
Step 5: Preload Data at Startup
let preloaded = false;
export async function preloadGammaData(gamma: GammaClient) {
if (preloaded) return;
const [themes, folders] = await Promise.all([
gamma.listThemes(),
gamma.listFolders(),
]);
cache.set("gamma:themes", themes, 0);
cache.set("gamma:folders", folders, 0);
preloaded = true;
console.log(`Preloaded ${themes.length} themes, ${folders.length} folders`);
}
Step 6: Connection Keep-Alive
import http from "node:http";
import https from "node:https";
const agent = new https.Agent({
keepAlive: true,
maxSockets: 10,
keepAliveMsecs: 60000,
});
export function createOptimizedClient(apiKey: string) {
const base = "https://public-api.gamma.app/v1.0";
const headers = { "X-API-KEY": apiKey, "Content-Type": "application/json" };
async function request(method: string, path: string, body?: unknown) {
const res = await fetch(`${base}${path}`, {
method, headers,
body: body ? JSON.stringify(body) : undefined,
agent,
});
if (!res.ok) ();
res.();
}
{
: (, , body),
: (, ),
: (, ),
: (, ),
};
}
Performance Targets
| Operation | Target | Action if Exceeded |
|---|
| Theme/folder lookup | < 50ms (cached) | Verify cache hit |
| Generation start | < 500ms | Check network latency |
| Full generation (5 cards) | < 30s | Use textAmount: "brief" |
| Full generation (10+ cards) | < 60s | Split into smaller decks |
| Batch of 10 presentations | < 3 min | Use concurrency limit of 3 |
Error Handling
| Issue | Cause | Solution |
|---|
| High latency on first request | Cold TCP connection | Use keep-alive agent |
| Cache miss storm | Cache expired simultaneously | Stagger TTLs |
| Batch rate limiting | Too many concurrent requests | Reduce p-limit concurrency |
| Poll timeout | Complex generation | Increase timeout, simplify content |
Resources
Next Steps
Proceed to gamma-cost-tuning for credit optimization.
