Set up OpenAI in the AppHost

This article is the reference for the Aspire OpenAI hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.ts — that you use to model an OpenAI parent resource and model resources in your AppHost project.

If you’re new to the OpenAI integration, start with the Get started with OpenAI integrations guide. For how consuming apps read the connection information this page exposes, see Connect to OpenAI.

Installation

To start building an Aspire app that uses OpenAI, install the 📦 Aspire.Hosting.OpenAI NuGet package:

C#

Terminal

aspire add openai

Learn more about aspire add in the command reference.

Or, choose a manual installation approach:

C# — AppHost.cs

#:package Aspire.Hosting.OpenAI@*

XML — AppHost.csproj

<PackageReference Include="Aspire.Hosting.OpenAI" Version="*" />

TypeScript

Terminal

aspire add openai

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the OpenAI hosting integration package:

aspire.config.json

{
  "packages": {
    "Aspire.Hosting.OpenAI": "13.3.0"
  }
}

Add OpenAI resource

Once you’ve installed the hosting integration in your AppHost project, you can add an OpenAI parent resource and then add one or more model resources beneath it:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai");

var chat = openai.AddModel("chat", "gpt-4o-mini");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const openai = await builder.addOpenAI("openai");

const chat = await openai.addModel("chat", "gpt-4o-mini");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

1. Calling AddOpenAI (or addOpenAI) creates an OpenAIResource that models the OpenAI account. It registers a secret parameter for the API key that defaults to the OPENAI_API_KEY environment variable.

2. Calling AddModel (or addModel) creates an OpenAIModelResource child whose connection string is composed from the parent endpoint, API key, and the model name you supply.

3. The AppHost reference call configures a connection in the consuming project named after the referenced model resource, such as chat in the preceding example. Multiple models can share the single API key and endpoint from the parent resource.

Note

When you reference an OpenAI model resource from the AppHost, Aspire makes several properties available to the consuming project, such as the endpoint URI, API key, and model name. For a complete list of these properties and per-language connection examples, see Connect to OpenAI.

Add multiple OpenAI model resources

Add multiple model children beneath the same parent to share a single API key and endpoint:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai");

var chat = openai.AddModel("chat", "gpt-4o-mini");
var embeddings = openai.AddModel("embeddings", "text-embedding-3-small");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat)
    .WithReference(embeddings);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const openai = await builder.addOpenAI("openai");

const chat = await openai.addModel("chat", "gpt-4o-mini");
const embeddings = await openai.addModel("embeddings", "text-embedding-3-small");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat)
    .withReference(embeddings);

// After adding all resources, run the app...

Referencing chat passes a connection string named chat to the project, and referencing embeddings passes a connection string named embeddings. Both share the parent API key and endpoint.

Use default API key parameter

Calling AddOpenAI("openai") (or addOpenAI("openai")) automatically creates a secret parameter named openai-openai-apikey. Aspire resolves its value in this order:

1. The Parameters:openai-openai-apikey configuration key (user secrets, appsettings.*, or environment variables).
2. The OPENAI_API_KEY environment variable.

If neither source provides a value, startup throws an exception. Provide the key via the Aspire CLI:

Terminal

aspire secret set Parameters:openai-openai-apikey sk-your-api-key

Use custom API key parameter

Replace the default parameter by creating your own secret parameter and passing it to WithApiKey (or withApiKey) on the parent:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var apiKey = builder.AddParameter("my-api-key", secret: true);

var openai = builder.AddOpenAI("openai")
                    .WithApiKey(apiKey);

var chat = openai.AddModel("chat", "gpt-4o-mini");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const apiKey = await builder.addParameter("my-api-key", { secret: true });

const openai = await builder.addOpenAI("openai");
await openai.withApiKey(apiKey);

const chat = await openai.addModel("chat", "gpt-4o-mini");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

Note

Parameters marked secret: true are stored in the user secrets store and never appear in plain text in logs or the dashboard.

Add a custom endpoint

Override the default https://api.openai.com/v1 endpoint to use a proxy, an Azure OpenAI endpoint, or any OpenAI-compatible gateway. Call WithEndpoint (or withEndpoint) on the parent resource:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai")
                    .WithEndpoint("https://my-gateway.example.com/v1");

var chat = openai.AddModel("chat", "gpt-4o-mini");

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const openai = await builder.addOpenAI("openai");
await openai.withEndpoint("https://my-gateway.example.com/v1");

const chat = await openai.addModel("chat", "gpt-4o-mini");

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

All model resources beneath the parent inherit the overridden endpoint. The overridden endpoint is reflected in the Endpoint and Uri connection properties that Aspire injects into consuming apps.

Add health check per model

Add an optional health check to a model resource to validate endpoint reachability, API key validity, and model existence at startup:

C#

C# — AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var openai = builder.AddOpenAI("openai");

var chat = openai.AddModel("chat", "gpt-4o-mini")
                 .WithHealthCheck();

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(chat);

// After adding all resources, run the app...

TypeScript

TypeScript — apphost.ts

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const openai = await builder.addOpenAI("openai");

const chat = await openai.addModel("chat", "gpt-4o-mini");
await chat.withHealthCheck();

await builder.addNodeApp("api", "./api", "index.js")
    .withReference(chat);

// After adding all resources, run the app...

The model health check validates endpoint reachability, API key validity (401), and model existence (404). It executes only once per application instance to limit rate-limit implications.

Note

In C#, each OpenAI parent resource also automatically registers a status-page health check against https://status.openai.com/api/v2/status.json. This status-page check is not currently exposed in the TypeScript AppHost.

Available models

Common model identifiers for the OpenAI API:

Category	Model identifiers
Chat	gpt-5, gpt-4o, gpt-4o-mini, gpt-4-turbo
Reasoning	o3, o3-mini, o4-mini
Realtime	gpt-realtime
Embeddings	text-embedding-3-small, text-embedding-3-large
Images	dall-e-3
Audio	whisper-1

For the full and up-to-date list, see the OpenAI models documentation.

Connection properties

For the full reference of OpenAI connection properties — and how consuming apps in C#, TypeScript, Python, and Go read them — see Connect to OpenAI.

See also

• Get started with the OpenAI integrations
• Connect to OpenAI
• OpenAI API documentation