@drawcall/generate-panorama

@drawcall/generate-panorama

Client SDK for generating 360° environment maps in the Drawcall Market environment format: a 2048×1024 background WebP plus a 1024×512 Radiance .hdr for Three.js PMREM/IBL lighting.

import { generate } from "@drawcall/generate-panorama";
import { writeFile } from "node:fs/promises";

const result = await generate({
  prompt: "a misty alpine valley at sunrise"
});

await writeFile("public/environment/alpine-valley.hdr", result.hdr);
await writeFile("public/environment/alpine-valley-background.webp", result.backgroundWebp);

Use one or more HTTPS image references when visual identity matters. A raw gameplay screenshot is sufficient; the service uses it for the world's visual language while excluding screenshot UI and first-person foreground:

const result = await generate({
  prompt: "environment for a floating jump and run",
  referenceImages: ["https://example.com/gameplay-screenshot.png"]
});

console.log(result.generatedDescription);

Describe the purpose naturally. A vision-aware planner infers grounded, elevated, and unbounded environments plus aerial height automatically:

const result = await generate({
  prompt: "Paris environment for a floating jump and run"
});

Up to four references are accepted as HTTPS URLs or data:image/<type>;base64,<data> URIs. The service validates, downloads, and downscales them to at most 1024 px before temporarily rehosting them, so the generation provider can reliably access them without unnecessary input cost. Each reference increases image-input cost and latency, so prefer one image or combine several references into a single contact sheet before calling the API.

Because a panorama has no translational parallax, the service keeps grounded features in a narrow band near the horizon and enforces a 200–250 m object-free region for every camera mode. Only a flat continuous ground surface may approach the viewer. Local 3D geometry should provide all nearby structures, vegetation, terrain relief, platforms, props, and effects.

The result includes both prompt, the original request, and generatedDescription, the improved self-contained description actually used for image generation.

The default API host is https://v1.panorama.api.drawcall.ai.

The pipeline generates the LDR panorama with GPT Image 2 (fal.ai), blends the equirectangular wraparound seam, and reconstructs HDR with LEDiff hosted on Modal.