openai

What it does

Provider. openai registers three handlers with registry in onInit: ("voiceover", "openai") over audio.speech.create, ("translate", "openai") over Chat Completions and ("prompt-gen", "openai") over the Responses API. It uses the official fetch-based openai SDK with its own retries off: the runner owns retries. The SDK client is built on the first execute and cached.

Every request is priced in USD twice: an offline estimate for the budget gate, and the actual cost from the usage the API reports. Prompts, completions and the key never appear in errors, logs or result metadata.

Its own public API is one method, app.openai.info().

Setup

One env var. Exported in the shell or in .env.local.

info() and every estimate() work without the key. Without it, voiceover and translate throw before any request:

[ai] OPENAI_API_KEY is not set.
  Export it or set config.apiKeyEnv to the variable that holds your key.

prompt-gen throws PromptGenUnavailableError with reason "auth" instead, so a promptGen fallback chain moves on to the next provider.

Tasks it serves

voiceover

text, voice, optional model and format. The model defaults to models.tts. format: mp3 (default) gives audio/mpeg, wav gives audio/wav, ogg is sent as opus and gives audio/ogg.

  - id: intro
    task: voiceover
    provider: openai
    input:
      text: "Welcome to the show!"
      voice: alloy
      format: mp3

translate

text, targetLang, optional sourceLang (else auto-detect) and model. A fixed translation system prompt and temperature: 0. The result is { text, costUsd, meta: { model, promptTokens, completionTokens } }. detectedSourceLang is never set.

  - id: greeting-ja
    task: translate
    input:
      text: "Hello, world!"
      targetLang: ja

prompt-gen

The same request contract as every prompt-gen provider: prompt or messages, system, tools, toolChoice, cacheSystem and params. The model defaults to models.chat. An openai/<id> alias is sent as <id>.

Prompt cache: cacheSystem and a text part with cache: true add a cache breakpoint on GPT-6 models, at most 4 per request. cacheTtl is ignored. Every other param is ignored.

Refused before any I/O with a terminal 400: an empty prompt or empty messages, a bad params.reasoning, a responseSchema that is not an object, params.images with messages.

  - id: sunset
    task: prompt-gen
    provider: openai
    input:
      prompt: "Describe a sunset over the ocean."
      model: gpt-6-luna
    params: { reasoning: low, max_tokens: 400 }

Models and prices

The plugin ships a price table in USD per one million tokens, or per one million characters for TTS. priceOverrides merges over it field by field. An unpriced model costs $0, and prompt-gen logs openai:prompt-gen:unpriced once per such model.

• Long context. A GPT-6 request above 272K input tokens pays every input-side rate × 2 and the output rate × 1.5.
• Missing cache rates fall back to the next rate up: cached input to input, 30m write to input, 12h write to 30m write.
• Estimates count tokens as chars / 4. Not a tokenizer. prompt-gen adds 1 600 tokens per image and prices max_output_tokens out, so the estimate is an upper bound.
• Actual cost comes from usage: uncached input, cache reads, 30m and 12h writes and output, each at its rate. No usage in the answer: chars / 4 of what was sent and received.

import { createApp } from "@moku-labs/ai";

const app = createApp({
  pluginConfigs: {
    openai: {
      models: { tts: "gpt-4o-mini-tts", chat: "gpt-4o" },
      priceOverrides: {
        "gpt-4o-2024-11-20": { inputPerM: 2.5, outputPerM: 10 }
      }
    }
  }
});

console.log(app.openai.info().models); // { tts: "gpt-4o-mini-tts", chat: "gpt-4o" }

Config

pluginConfigs.openai.

API

Mounted at app.openai.

import { app } from "./app";

const { configured, models } = app.openai.info();
console.log(configured, models.chat); // true, "gpt-4o-mini"

Types ship under the Openai namespace: Openai.Config, Openai.ModelPrice, Openai.OpenaiApi.

Errors

classifyOpenaiError maps every SDK error to one of three classes. The runner reads status, kind and retryAfterMs by shape.

Content policy is found two ways: an SDK error whose body carries a content_policy, content_filter or moderation marker, or an answer that refuses. For translate that is a non-null refusal. For prompt-gen it is a refusal part, or incomplete with reason content_filter.

An abort through opts.signal is rethrown unchanged. Every thrown message is a fixed string. The SDK's own message is never echoed.

The classes are values under OpenaiErrors:

import { OpenaiErrors } from "@moku-labs/ai";
import { app } from "./app";

try {
  await app.translate.generate({ text: "Hello", targetLang: "es" }, { provider: "openai" });
} catch (error) {
  if (error instanceof OpenaiErrors.RetryableProviderError) {
    console.warn("transient", error.status ?? error.kind, error.retryAfterMs);
  } else if (error instanceof OpenaiErrors.FlaggedProviderError) {
    console.error("refused");
  } else {
    throw error;
  }
}

Events

Emits

None.

Listens to

None. Diagnostics go through ctx.log: openai:tts:done, openai:translate:done, openai:prompt-gen:done with model and token or character counts, the :failed twins with the error class and status, and openai:prompt-gen:unpriced. No text.

Depends on

• registry: the three register calls.

Related

• voiceover, translate, prompt-gen: the tasks.
• anthropic, codex, claude: the other prompt-gen providers.
• runner: how the error classes become retries.