openai://¶

OpenAI's hosted chat-completions and embeddings API. The canonical client-side LLM component — sends a single user message (plus an optional system prompt) to POST /v1/chat/completions or POST /v1/embeddings and writes the model's text or embedding vector back onto the exchange body. Reach for this when you want OpenAI itself, or when you want to talk to a third-party OpenAI-compatible server (local proxies, OpenAI-style gateways, LM Studio, etc.) — set baseURL to override the endpoint.

For a list of supported provider-specific schemes built on the same shape (Mistral, Fireworks, Groq, Together, xAI, vLLM, DeepInfra, Hugging Face, etc.), see the providers guide.

URI shape¶

openai://chat?model=<id>&apiKey=<key>&temperature=<float>&maxTokens=<int>&baseURL=<url>
openai://embeddings?model=<id>&apiKey=<key>&baseURL=<url>

The path token (chat or embeddings) is required — openai:// with no operation is rejected.

Parameters¶

Plus the shared LLM-provider params from pkg/component/llmutil (seed, topP, topK, stop, responseFormat, reasoningEffort, verbosity — see the LLM providers guide).

No consumer; openai:// is producer-only. See openai-server if you want to receive OpenAI-format requests from external clients.

Headers¶

The producer reads one optional header from the exchange before the request goes out:

After a successful call, the producer sets these headers on the exchange:

These plug straight into the cost/tokens reporting stack — see the observability guide.

Examples¶

Single chat call with a system prompt set upstream:

- id: chat
  from: direct://summarize
  steps:
    - setHeader:
        name: systemPrompt
        starlang: |
          %sl 2.0
          output text/plain
          ---
          "You are a terse summariser. Reply in one sentence."
    - to: openai://chat?model=gpt-4o&apiKey=${OPENAI_API_KEY}

Embeddings — body in, vector out:

- id: embed
  from: direct://embed
  steps:
    - to: openai://embeddings?model=text-embedding-3-small&apiKey=${OPENAI_API_KEY}

Batch embeddings — []string body in, list of vectors out:

- id: embed-batch
  from: direct://embed-batch
  steps:
    - to: openai://embeddings?model=text-embedding-3-small&apiKey=${OPENAI_API_KEY}
  # The body is set upstream to []string{"doc1", "doc2", "doc3"} —
  # output body is a []any of three vectors; openai.embedding.count = 3.

Reduced-dimension embeddings (text-embedding-3-* only):

- to: openai://embeddings?model=text-embedding-3-large&dimensions=256&apiKey=${OPENAI_API_KEY}

Bandwidth-saving embeddings via encodingFormat=base64:

- to: openai://embeddings?model=text-embedding-3-small&encodingFormat=base64&apiKey=${OPENAI_API_KEY}

Strict policy message via the new developer role:

- to: openai://chat?model=gpt-4o&developerMessage=Always%20respond%20in%20JSON.&apiKey=${OPENAI_API_KEY}

Audit-trail flow — capture the raw OpenAI response for replay/replay:

- to: openai://chat?model=gpt-4o&storeFullResponse=true&apiKey=${OPENAI_API_KEY}
- to: file:audit?fileName=${date:now:yyyyMMdd-HHmmss}.json&body=${header.openai.response}

Point at a third-party OpenAI-compatible endpoint (e.g. an internal proxy):

- to: openai://chat?model=gpt-4o&baseURL=https://gateway.internal/v1&apiKey=${PROXY_KEY}

Behavior notes¶

• HTTP only. This component does not stream — it reads the full JSON response (capped at 100 MB) and replaces the exchange body with the assistant message text (or the first embedding vector). For token-by-token streaming through routes, use the agent component or a multimodal route step.
• Single-turn. The component sends exactly one user turn per call. Multi-turn conversation is the responsibility of the caller — use memory on the agent layer if you need history.
• 120s default timeout on the underlying http.Client.
• No automatic retries. A non-200 response is surfaced as an error; wrap in a resilience processor if you need backoff.
• Vision is supported directly at the URI seam — see Multimodal input below. Function calling is not yet at the URI seam — use the agent component for that.
• The OpenAI model catalogue lists every chat and embedding id that this component will accept.

Multimodal input¶

openai://chat accepts vision input alongside text. The component detects the input shape from the exchange body and Helix-only headers listed below, then serialises into OpenAI's image_url content-block format. Use a vision-capable model (gpt-4o, gpt-4o-mini, gpt-4-turbo, etc.) — text-only models will reject the request.

Input shapes accepted¶

Multimodal headers¶

Examples¶

Caption a PNG from disk¶

- id: caption-image
  from: file:///inbox?include=.*\.png$
  steps:
    - set-header:
        name: HelixLLMSystemPrompt
        constant: "Describe this image in one paragraph."
    - to: openai://chat?model=gpt-4o&apiKey=${env:OPENAI_API_KEY}&imageDetail=high

Mixed text + image (URL)¶

- set-body: "Is this medication safe with metformin?"
- set-header:
    name: HelixLLMImages
    starlang: |
      [ "https://internal.example.com/pills/r4291.jpg" ]
- to: openai://chat?model=gpt-4o&apiKey=${env:OPENAI_API_KEY}

Per-page PDF→markdown via direct VLM¶

# Upstream step rendered a PDF page to PNG bytes on the body.
- set-header:
    name: HelixLLMSystemPrompt
    constant: |
      Convert this page to clean Markdown.
      Preserve every dosage, route, and frequency verbatim.
      Render tables as Markdown tables.
- to: openai://chat?model=gpt-4o&apiKey=${env:OPENAI_API_KEY}&maxTokens=4096&imageDetail=high

GPT-5 / o-series reasoning models¶

The openai:// component auto-detects reasoning-family models by prefix (o1*, o3*, o4*, gpt-5*) and adapts the wire shape:

You no longer need to manually set temperature=1 for reasoning models — Helix omits the field, OpenAI uses its default. Same behaviour across openai://, vlm://?provider=openai, and agent:// with an OpenAI provider.

URI knobs (all OpenAI-shape only — Anthropic / Ollama / Vertex ignore):

Per-request overrides via headers: - HelixLLMReasoningEffort - HelixLLMVerbosity

# GPT-5 reasoning call — Helix sends max_completion_tokens and omits temperature.
- to: openai://chat
  params:
    model: gpt-5
    apiKey: ${env:OPENAI_API_KEY}
    # temperature: not needed — Helix auto-omits for reasoning models
    maxTokens: 16384            # → max_completion_tokens on the wire
    reasoningEffort: high       # minimal | low | medium | high | xhigh
    verbosity: medium
    seed: 42
    responseFormat: json_object

Not yet supported: the Responses API (/v1/responses). For gpt-5-pro / gpt-5.2-pro that may require it, use the agent layer or wait for the Responses-API round.

Source¶

• pkg/component/openai/openai.go
• pkg/component/openai/openai_test.go

See also¶

• openai-server — the inverse: expose Helix agents under an OpenAI-compatible REST API.
• anthropic, vertex, bedrock — alternative non-OpenAI clients.
• mistral, fireworks, groq, together, xai, vllm, deepinfra, huggingface, azure — OpenAI-compatible providers sharing this same request/response shape via pkg/component/llmutil.
• providers guide — comparison and selection criteria.