API Reference

Get a handle with ai(name) from @alienplatform/sdk. The AI surface is TypeScript only — there is no Rust binding. Workloads in other languages call the HTTP endpoints directly.

The binding environment variable

A linked AI resource injects ALIEN_<NAME>_BINDING (uppercased, hyphens to underscores — a resource named llm becomes ALIEN_LLM_BINDING) containing a JSON object tagged by service:

The three cloud variants carry no key: the workload's own identity authorizes each call. external-ai carries a provider API key, and the SDK calls that provider directly.

chat.completions.create

Sends an OpenAI Chat Completions request. Use this for every model except Claude and the GPT-5 family.

const completion = await ai("llm").chat.completions.create({
  model: "gpt-oss-120b",
  messages: [{ role: "user", content: "Summarize this order." }],
})

const stream = await ai("llm").chat.completions.create({
  model: "gpt-oss-120b",
  messages: [{ role: "user", content: "Summarize this order." }],
  stream: true,
})
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
}

Any other field is passed to the provider untouched.

Returns: ChatCompletion, or AsyncIterable<ChatCompletionChunk> when stream is true.

responses.create

Sends an OpenAI Responses request. AWS only. The GPT-5 family serves this API and no other; gpt-oss-20b and gpt-oss-120b serve it as well as chat completions.

const response = await ai("llm").responses.create({
  model: "gpt-5.5",
  input: "Summarize this order.",
})

Returns: Response, or AsyncIterable<ResponseStreamEvent> when stream is true.

Errors: AI_RESPONSES_API_UNSUPPORTED on a bring-your-own-key Anthropic binding, which serves no Responses endpoint.

getAvailableModels

Lists the models this deployment can invoke right now.

const models = await ai("llm").getAvailableModels()
// [{ id: "gpt-oss-20b", provider: "openai", displayName: "GPT-OSS 20B" }, …]

Returns: AiModel[], checked against the customer's cloud on the first call and reused after that, so a model their account has not enabled is normally absent — see Behavior for when one can still appear. On a bring-your-own-key binding it is a fixed list for that provider.

getAiConnection

Resolves a binding to an endpoint you can hand to another client library.

import { createOpenAICompatible } from "@ai-sdk/openai-compatible"
import { getAiConnection } from "@alienplatform/sdk"

const connection = await getAiConnection("llm")
const model = createOpenAICompatible({
  name: "alien",
  ...connection,
  apiKey: connection.apiKey ?? "",
})("gpt-oss-120b")

Returns: AiConnection, ready to use — the endpoint is live by the time it resolves.

Pass apiKey: "" on a cloud binding rather than leaving it unset. Most clients fall back to a provider key in the environment when the field is missing, and would send your personal ANTHROPIC_API_KEY or OPENAI_API_KEY instead of using the workload's identity.

Calling the endpoints directly

The endpoint runs beside your workload. getAiConnection() returns its address, and the baseURL already includes the resource segment and /v1.

const { baseURL } = await getAiConnection("llm")

await fetch(`${baseURL}/chat/completions`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    model: "gpt-oss-120b",
    messages: [{ role: "user", content: "hi" }],
  }),
})

On a cloud binding no credentials go on these calls: the endpoint is reachable only from inside your workload, and every request to the provider is signed with the workload's own cloud identity. A bring-your-own-key binding is different — baseURL is the provider's own URL and you must send apiKey as a bearer token yourself.

Never hardcode the port — it is not fixed. A workload in another language reads ALIEN_AI_GATEWAY_URL and appends /{name}/v1, where {name} is the resource id lowercased with underscores replaced by hyphens.

Types

interface AiConnection {
  baseURL: string        // ends in /v1, ready for an OpenAI- or Anthropic-compatible client
  apiKey?: string        // bring-your-own-key bindings only; `undefined` on the clouds
}

interface AiModel {
  id: string             // pass as `model`
  provider: string       // "openai" | "anthropic" | "google" | "mistral" | …
  displayName: string    // human label, for a model picker
}

ChatCompletion, ChatCompletionChunk, Response, and ResponseStreamEvent come from the openai package, an optional peer dependency. Install it for the types; it is not needed at runtime.

Errors

Match on error.code. AiUpstreamError and AiTransportError are importable classes; the rest are codes on an AlienError rather than exported types.

A failed model call surfaces as AI_UPSTREAM_ERROR carrying the status the provider returned, so retry on the retryable statuses above and treat the rest as permanent.