Gamma Hello World

Overview

Generate your first presentation using Gamma's async Generate API. The workflow is: POST to create a generation, poll for status, then retrieve results (gammaUrl + exportUrl).

Prerequisites

• Completed gamma-install-auth setup
• Valid GAMMA_API_KEY environment variable
• Pro account with available credits

The Generate-Poll-Retrieve Pattern

All Gamma generations are asynchronous:

1. POST /v1.0/generations — submit content, receive generationId
2. GET /v1.0/generations/{generationId} — poll every 5s until completed or failed
3. Result — gammaUrl (view in app) + exportUrl (download PDF/PPTX/PNG)

Instructions

Minimal curl Example

bash
# Step 1: Create generation
GENERATION=$(curl -s -X POST \
  "https://public-api.gamma.app/v1.0/generations" \
  -H "X-API-KEY: ${GAMMA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Create a 5-card presentation about the benefits of AI in business",
    "outputFormat": "presentation"
  }')

GEN_ID=$(echo "$GENERATION" | jq -r '.generationId')
echo "Generation started: $GEN_ID"

# Step 2: Poll until complete (every 5 seconds)
while true; do
  STATUS=$(curl -s \
    "https://public-api.gamma.app/v1.0/generations/${GEN_ID}" \
    -H "X-API-KEY: ${GAMMA_API_KEY}")
  STATE=$(echo "$STATUS" | jq -r '.status')
  echo "Status: $STATE"
  [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ] && break
  sleep 5
done

# Step 3: Retrieve results
echo "$STATUS" | jq '{gammaUrl, exportUrl, creditsUsed}'

Node.js / TypeScript Example

typescript
const GAMMA_BASE = "https://public-api.gamma.app/v1.0";
const headers = {
  "X-API-KEY": process.env.GAMMA_API_KEY!,
  "Content-Type": "application/json",
};

async function generatePresentation(content: string) {
  // Step 1: Create generation
  const createRes = await fetch(`${GAMMA_BASE}/generations`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      content,
      outputFormat: "presentation",
    }),
  });
  if (!createRes.ok) throw new Error(`Create failed: ${createRes.status}`);
  const { generationId } = await createRes.json();
  console.log(`Generation started: ${generationId}`);

  // Step 2: Poll for completion
  while (true) {
    const pollRes = await fetch(`${GAMMA_BASE}/generations/${generationId}`, { headers });
    const result = await pollRes.json();

    if (result.status === "completed") {
      console.log(`View: ${result.gammaUrl}`);
      console.log(`Download: ${result.exportUrl}`);
      console.log(`Credits used: ${result.creditsUsed}`);
      return result;
    }
    if (result.status === "failed") {
      throw new Error(`Generation failed: ${JSON.stringify(result)}`);
    }
    console.log(`Status: ${result.status}...`);
    await new Promise((r) => setTimeout(r, 5000));
  }
}

// Run it
await generatePresentation("Create a 5-card intro to machine learning");

Python Example

python
import os, time, requests

BASE = "https://public-api.gamma.app/v1.0"
HEADERS = {
    "X-API-KEY": os.environ["GAMMA_API_KEY"],
    "Content-Type": "application/json",
}

def generate_presentation(content: str) -> dict:
    # Step 1: Create
    resp = requests.post(f"{BASE}/generations", headers=HEADERS, json={
        "content": content,
        "outputFormat": "presentation",
    })
    resp.raise_for_status()
    gen_id = resp.json()["generationId"]
    print(f"Generation started: {gen_id}")

    # Step 2: Poll
    while True:
        poll = requests.get(f"{BASE}/generations/{gen_id}", headers=HEADERS)
        result = poll.json()
        if result["status"] == "completed":
            print(f"View: {result['gammaUrl']}")
            print(f"Download: {result['exportUrl']}")
            return result
        if result["status"] == "failed":
            raise Exception(f"Failed: {result}")
        print(f"Status: {result['status']}...")
        time.sleep(5)

generate_presentation("5-card intro to sustainable energy")

Expected Output

json
{
  "generationId": "gen_abc123",
  "status": "completed",
  "gammaUrl": "https://gamma.app/docs/Benefits-of-AI-abc123",
  "exportUrl": "https://export.gamma.app/gen_abc123.pdf",
  "creditsUsed": 42
}

Output Formats

| outputFormat | Result | |----------------|--------| | presentation | Slide deck (default) | | document | Long-form document | | webpage | Web page | | social_post | Social media content |

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 401 on POST | Bad API key | Verify X-API-KEY header | | 422 on POST | Invalid parameters | Check content and outputFormat values | | status: "failed" | Generation could not complete | Simplify content or reduce card count | | Poll timeout | Very large generation | Increase poll duration beyond 2 minutes |

Resources

• Generate a Gamma
• Generate API Parameters
• Explore the API

Next Steps

Proceed to gamma-core-workflow-a for advanced generation with themes, images, and export options.