Call OpenAI models with an integration

Connect the OpenAI integration and Func gets ctx.ai.openai: chat, translate, extract structured data, make a single tool call, generate images. The API key stays on the server and never appears in your code.

Connect OpenAI

Open Backend → Integrations in the editor, pick OpenAI, and fill in the form below. Saving makes a real call upstream, so a bad key fails right there instead of the first time a visitor uses the feature.

chat: one call

ctx.ai.openai.chat(params) makes one call and returns the complete result.

export function translate(input, ctx) {
  const r = ctx.ai.openai.chat({
    messages: [
      { role: 'system', content: 'Translate the user input into English. Output only the translation.' },
      { role: 'user', content: input.text },
    ],
    model: 'gpt-4o-mini',   // omit to use the integration's default
    temperature: 0.2,
    maxTokens: 512,
  })
  return { text: r.content, tokens: r.totalTokens }
}

The result:

Ask for JSON with json: true

Getting JSON out of a model is the most common use of this capability: translation, extraction and classification all end there. With json: true the platform strips the code fence models love to add and parses what is left into data.

export function extract(input, ctx) {
  const r = ctx.ai.openai.chat({
    messages: [{ role: 'user', content: `Extract the name and city as JSON: ${input.text}` }],
    json: true,
  })
  return { name: r.data.name, city: r.data.city }
}

A single tool call

Pass tools and toolCalls comes back when the model wants one. The typical use is a single round: turn the user's sentence into one structured function call, run it yourself, then answer.

export function assistant(input, ctx) {
  const r = ctx.ai.openai.chat({
    messages: [{ role: 'user', content: input.text }],
    tools: [{
      type: 'function',
      function: {
        name: 'reschedule',
        description: 'Move a meeting to another date',
        parameters: {
          type: 'object',
          properties: { meetingId: { type: 'string' }, date: { type: 'string' } },
          required: ['meetingId', 'date'],
        },
      },
    }],
    toolChoice: 'auto',
  })

  if (r.toolCalls?.length) {
    const c = r.toolCalls[0]
    // c.arguments is already an object
    ctx.db.update('meetings', c.arguments.meetingId, { date: c.arguments.date })
    return { done: true }
  }
  return { reply: r.content }
}

A second round is yours to run: append the tool result to messages and call again.

const r2 = ctx.ai.openai.chat({
  messages: [
    { role: 'user', content: input.text },
    { role: 'assistant', toolCalls: r.toolCalls },              // replay what the model asked for
    { role: 'tool', toolCallId: r.toolCalls[0].id, content: JSON.stringify(result) },
  ],
})

The platform does not run that loop for you. When to stop, whether a tool may read the database, how the timeout is spent: only your site knows.

Generate images

ctx.ai.openai.image(params). Use upload: true and the image is stored in your project's own space, with a permanent URL back.

export const config = { timeoutMs: 120000 }   // image generation takes tens of seconds

export function cover(input, ctx) {
  const r = ctx.ai.openai.image({
    prompt: input.prompt,
    size: '1024x1024',
    quality: 'high',
    upload: true,
  })
  return { url: r.images[0].fileUrl }
}

Returns { model, images: [...] }, where each image is { fileUrl | imageBase64, mimeType, bytes, revisedPrompt? }.

Escape hatches: extra and call

For fields the platform does not expose, use extra. It is merged into the request body as-is and cannot break messages:

ctx.ai.openai.chat({
  messages,
  extra: { top_p: 0.9, seed: 42, response_format: { type: 'json_object' } },
})

For endpoints other than /chat/completions, use call(path, body). The body goes up as-is, the upstream JSON comes back as-is, and the key still never enters the sandbox:

const r = ctx.ai.openai.call('/embeddings', {
  model: 'text-embedding-3-small',
  input: input.text,
})
const vector = r.data[0].embedding

Several channels: via(tag)

A project can hold several OpenAI configurations, say a cheap model for classification and a strong one for writing, or one official endpoint and one self-hosted gateway. Tag each configuration and pick one with via():

ctx.ai.openai.via('cheap').chat({ messages })
ctx.ai.openai.via('strong').chat({ messages })

Without via() the configuration tagged default is used.

Reading the errors

Upstream errors (out of quota, unknown model, rate limited) keep their message but come back as 400 or 502. An upstream 401 is never passed through as-is, since that would make the page think the visitor is signed out.

What this does not do

See also: More integrations, Text to speech, Func backend capabilities.