Quickstart

Make your first API call to Heroku AI and build a simple web search assistant

Make your first API call to Heroku AI and build a simple web search assistant using Claude models.

Prerequisites

• A Heroku account
• Heroku CLI installed
• An inference API key (generated during model provisioning)

Call the API

cURL

1. Set your API key

   Get your API key from the Heroku Dashboard after provisioning a model and set it as an environment variable:

   export INFERENCE_KEY='your-api-key-here'
   
2. Make your first API call

   Run this command to create a simple web search assistant:

   curl https://us.inference.heroku.com/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $INFERENCE_KEY" \
     -d '{
       "model": "claude-4-5-sonnet",
       "max_tokens": 1000,
       "messages": [
         {
           "role": "user",
           "content": "What should I search for to find the latest developments in renewable energy?"
         }
       ]
     }'
   

   Example output:

   {
     "id": "msg_01HCDu5LRGeP2o7s2xGmxyx8",
     "type": "message",
     "role": "assistant",
     "content": [
       {
         "type": "text",
         "text": "Here are some effective search strategies to find the latest renewable energy developments:\n\n## Search Terms to Use:\n- \"renewable energy news 2024\"\n- \"clean energy breakthrough\"\n- \"solar/wind/battery technology advances\"\n- \"green energy innovations\"\n- \"climate tech developments\"\n- \"energy storage solutions\"\n\n## Best Sources to Check:\n\n**News & Industry Sites:**\n- Renewable Energy World\n- GreenTech Media (now Wood Mackenzie)\n- Energy Storage News\n- CleanTechnica\n- PV Magazine (for solar)\n- WindPower Engineering & Development..."
       }
     ],
     "model": "claude-4-5-sonnet",
     "stop_reason": "end_turn",
     "usage": {
       "input_tokens": 21,
       "output_tokens": 305
     }
   }
   

Python

1. Set your API key

   Get your API key from the Heroku Dashboard after provisioning a model and set it as an environment variable:

   export INFERENCE_KEY='your-api-key-here'
   
2. Install the OpenAI SDK

   Heroku AI uses OpenAI-compatible endpoints, so install the OpenAI Python SDK:

   pip install openai
   
3. Create your code

   Save this as quickstart.py:

   from openai import OpenAI
   import os
   
   client = OpenAI(
       base_url="https://us.inference.heroku.com/v1",
       api_key=os.environ.get("INFERENCE_KEY")
   )
   
   response = client.chat.completions.create(
       model="claude-4-5-sonnet",
       max_tokens=1000,
       messages=[
           {
               "role": "user",
               "content": "What should I search for to find the latest developments in renewable energy?"
           }
       ]
   )
   print(response.choices[0].message.content)
   
4. Run your code

   python quickstart.py
   

   Example output:

   Here are some effective search strategies for finding the latest renewable energy developments:
   
   **Search Terms to Use:**
   - "renewable energy news 2024"
   - "clean energy breakthroughs"
   - "solar/wind/battery technology advances"
   - "energy storage innovations"
   - "green hydrogen developments"
   - "renewable energy policy updates"
   
   **Reliable Sources to Check:**
   - **News & Analysis:** Reuters Energy, Bloomberg New Energy Finance, Greentech Media, Energy Storage News
   - **Industry Publications:** Renewable Energy World, PV Magazine, Wind Power Engineering
   - **Research Organizations:** International Energy Agency (IEA), National Renewable Energy Laboratory (NREL)
   - **Government Sources:** Department of Energy websites, EPA clean energy updates
   
   **Specific Topics to Explore:**
   - Perovskite and next-gen solar cells
   - Offshore wind expansion
   - Grid-scale battery storage
   - Green hydrogen production
   - Carbon capture technologies
   - Smart grid innovations
   - Energy policy changes and incentives...
   

TypeScript

1. Set your API key

   Get your API key from the Heroku Dashboard after provisioning a model and set it as an environment variable:

   export INFERENCE_KEY='your-api-key-here'
   
2. Install the OpenAI SDK

   Heroku AI uses OpenAI-compatible endpoints, so install the OpenAI TypeScript SDK:

   npm install openai
   
3. Create your code

   Save this as quickstart.ts:

   import OpenAI from "openai";
   
   async function main() {
     const client = new OpenAI({
       baseURL: "https://us.inference.heroku.com/v1",
       apiKey: process.env.INFERENCE_KEY
     });
   
     const response = await client.chat.completions.create({
       model: "claude-4-5-sonnet",
       max_tokens: 1000,
       messages: [
         {
           role: "user",
           content: "What should I search for to find the latest developments in renewable energy?"
         }
       ]
     });
     console.log(response.choices[0].message.content);
   }
   
   main().catch(console.error);
   
4. Run your code

   npx tsx quickstart.ts
   

   Example output:

   Here are some effective search strategies to find the latest renewable energy developments:
   
   ## Search Terms to Use:
   - "renewable energy news 2024"
   - "clean energy breakthroughs"
   - "solar wind technology advances"
   - "energy storage innovations"
   - "green hydrogen developments"
   - "offshore wind projects"
   - "battery technology renewable"
   
   ## Best Sources to Check:
   
   **News & Industry Sites:**
   - Renewable Energy World
   - CleanTechnica
   - GreenTech Media (now Wood Mackenzie)
   - Energy Storage News
   - PV Magazine (for solar)...
   

Java

1. Set your API key

   Get your API key from the Heroku Dashboard after provisioning a model and set it as an environment variable:

   export INFERENCE_KEY='your-api-key-here'
   
2. Add HTTP client dependency

   Add an HTTP client to your project. For Maven:

   <dependency>
     <groupId>com.squareup.okhttp3</groupId>
     <artifactId>okhttp</artifactId>
     <version>4.12.0</version>
   </dependency>
   <dependency>
     <groupId>com.google.code.gson</groupId>
     <artifactId>gson</artifactId>
     <version>2.10.1</version>
   </dependency>
   
3. Create your code

   Save this as QuickStart.java:

   import okhttp3.*;
   import com.google.gson.Gson;
   import java.io.IOException;
   import java.util.Map;
   
   public class QuickStart {
       public static void main(String[] args) throws IOException {
           OkHttpClient client = new OkHttpClient();
   
           String json = new Gson().toJson(Map.of(
               "model", "claude-4-5-sonnet",
               "max_tokens", 1000,
               "messages", new Object[] {
                   Map.of(
                       "role", "user",
                       "content", "What should I search for to find the latest developments in renewable energy?"
                   )
               }
           ));
   
           RequestBody body = RequestBody.create(
               json,
               MediaType.parse("application/json")
           );
   
           Request request = new Request.Builder()
               .url("https://us.inference.heroku.com/v1/chat/completions")
               .addHeader("Authorization", "Bearer " + System.getenv("INFERENCE_KEY"))
               .post(body)
               .build();
   
           try (Response response = client.newCall(request).execute()) {
               System.out.println(response.body().string());
           }
       }
   }
   
4. Run your code

   javac QuickStart.java
   java QuickStart
   

   Example output:

   {
     "id": "msg_01abc123",
     "type": "message",
     "role": "assistant",
     "content": [
       {
         "type": "text",
         "text": "Here are some effective search strategies to find the latest renewable energy developments:\n\n## Search Terms to Use:\n- \"renewable energy news 2024\"\n- \"clean energy breakthroughs\"..."
       }
     ],
     "model": "claude-4-5-sonnet",
     "stop_reason": "end_turn",
     "usage": {
       "input_tokens": 21,
       "output_tokens": 305
     }
   }
   

Next steps

Now that you have made your first Heroku AI API request, it’s time to explore what else is possible:

Chat Completions

OpenAI-compatible API for all models.

Messages API

Native Anthropic SDK for Claude models.

Choose a Model

Find the right model for your use case and budget.

AI Studio

Test models interactively before integrating.

Provisioning your first model

If you haven’t provisioned a model yet, use the Heroku CLI:

# Login to Heroku
heroku login

# Create a new app (or use an existing one)
heroku create my-ai-app

# Provision a Claude model
heroku ai:models:create claude-4-5-sonnet --app my-ai-app

# Get your API key
heroku config:get INFERENCE_KEY --app my-ai-app

For more details on provisioning and managing models, see the CLI Commands documentation.