Documentation

API Reference

One endpoint turns any photo into a walkable 3D world with correct materials, lighting, and geometry — including what's behind objects.

Quickstart

Generate your first 3D world in under 5 minutes.

terminal

# Install the SDK
pip install forerunner

# Set your API key
export FORERUNNER_API_KEY="fr_live_..."

# Generate a 3D world from a single photo
curl -X POST https://api.forerunner.ai/v1/generate \
  -H "Authorization: Bearer $FORERUNNER_API_KEY" \
  -F "image=@photo.jpg" \
  -F "materials=true" \
  -F "fill_occluded=true" \
  -F "output=spz"

# Returns: ~20MB surfel scene → 60fps on iPhone

Guides

Authentication

Create API keys, manage scopes, and authenticate requests with Bearer tokens.

Generate 3D World

The core endpoint. Upload one photo, get a complete 3D Gaussian Splat scene with geometry, materials, and occlusion completion.

PBR Materials

Enable material prediction to get relightable scenes. Metal, glass, concrete, fabric, wood, skin — all from a single photo.

Occlusion Completion

Fill in hidden geometry behind objects and around corners. Predictions are grounded with real-world geospatial and depth data for metric accuracy.

Output Formats

Surfel Scene (.spz), PLY, USDZ, glTF, and compact mobile format. ~20MB output renders at 60fps on iPhone.

Async Jobs & Webhooks

Submit batch jobs for multiple scenes. Poll for status or receive webhook callbacks on completion.

Endpoints

Base URL: https://api.forerunner.ai

Method	Endpoint	Description	Parameters
POST	/v1/generate	Generate 3D world from a single photo	image, materials, fill_occluded, output
POST	/v1/generate/batch	Submit batch of photos for 3D generation	images[], materials, webhook_url
GET	/v1/jobs/:id	Poll async job status	—
GET	/v1/jobs/:id/download	Download completed 3D scene	format

POST /v1/generate

The core endpoint. Upload a single photo and receive a complete 3D world.

Request Parameters

image

filerequired

JPEG or PNG photo

description

string

Rich text description of the scene — lighting, materials, atmosphere, spatial layout. Supports long-form prompts.

materials

bool

Enable PBR material prediction (default: false)

fill_occluded

bool

Generate hidden geometry (default: false)

output

string

spz, ply, usdz, gltf (default: spz)

quality

string

standard, high, ultra (default: standard)

Response

{
  "id": "gen_a1b2c3d4",
  "status": "completed",
  "scene": {
    "format": "spz",
    "size_bytes": 21495808,
    "num_surfels": 2847392,
    "download_url": "https://..."
  },
  "materials": {
    "detected": ["concrete", "metal", "glass"],
    "relightable": true
  },
  "geometry": {
    "occluded_filled": true,
    "coverage_degrees": 312
  },
  "processing_ms": 890
}

Authentication

All API requests require a Bearer token. Create API keys in your dashboard.

Authorization: Bearer fr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usage-based pricing coming soon

Free tier included. Per-scene rates announced at launch.

Join the waitlist →