# OpenAI

Ask OpenAI models for text or JSON (with files, images, web search and code interpreter), check text for policy violations, make embeddings, generate and edit images, turn text into speech, transcribe and translate audio, and manage files and conversations.

## Connect OpenAI

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `openai` and choose **OpenAI**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **API Key · Required**: Your OpenAI secret key (sk-…).
- **Organization ID · Optional**: Optional. The organization to bill (org-…), for a key that belongs to several. Sent as OpenAI-Organization.
- **Project ID · Optional**: Optional. The project to bill (proj_…), for a key that is not a project key. Sent as OpenAI-Project.

Paste an OpenAI API key (platform.openai.com → API keys → Create new secret key). A key made for a project bills that project; the organization and project fields are only for a key that belongs to several.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Do things in OpenAI

Add an **OpenAI** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Text](https://docs.gorunner.io/apps/openai#fields-f-text): Message a Model · Classify Text for Violations
- [Image](https://docs.gorunner.io/apps/openai#fields-f-image): Analyze Image · Generate an Image · Edit Image
- [Audio](https://docs.gorunner.io/apps/openai#fields-f-audio): Generate Audio · Transcribe a Recording · Translate a Recording
- [File](https://docs.gorunner.io/apps/openai#fields-f-file): Upload a File · List Files · Get a File · Delete a File
- [Conversation](https://docs.gorunner.io/apps/openai#fields-f-conversation): Create · Get · Update · Remove
- [Embedding](https://docs.gorunner.io/apps/openai#fields-f-embedding): Create
- [Model](https://docs.gorunner.io/apps/openai#fields-f-model): List Models

To start a workflow from OpenAI, use a [Schedule](https://docs.gorunner.io/apps/schedule), [Webhook](https://docs.gorunner.io/apps/webhook) or [Form](https://docs.gorunner.io/apps/form) trigger.

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from OpenAI can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When OpenAI says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, OpenAI is `pieceId: "openai"` with `actionId: "openai"`, set by `resource` and an `operation_…` field, such as `operation_audio`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### OpenAI › Text

### Message a Model

- **Model · Optional**: The model that answers. Default: gpt-6-luna.
- **Instructions · Optional**: Optional. How the model should behave: its role, tone, rules (a system message).
- **Prompt · Required**: What to ask or tell the model.
- **Files · Optional**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). Optional. Images and documents (PDF, text, spreadsheets …) the model reads with the prompt; 50 MB in all.
- **Output Format · Optional**: Text, or JSON a later step can read field by field (parsed under json). Options: Text, JSON matching a schema, Any JSON object. Default: Text.
- **JSON Schema · Required**: The shape of the answer, as JSON Schema, such as {"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}. Every property must be listed in required, and every object needs "additionalProperties": false. Shows when **Output Format** is **JSON matching a schema**.
- **Schema Name · Optional**: A name for the schema (letters, digits, _ and -, up to 64). Default: result. Shows when **Output Format** is **JSON matching a schema**.
- **Web Search · Optional**: Let the model search the web and cite what it finds. Off by default.
- **Code Interpreter · Optional**: Let the model write and run Python in OpenAI's sandbox (billed per session). Off by default.
- **File Search Vector Stores · Optional**: Optional. Vector store ids (vs_…), comma separated, for the model to search with file search.
- **Conversation · Optional**: Optional. A conversation id (conv_…): the model reads its history, and the prompt and answer are added to it.
- **Previous Response · Optional**: Optional. The id of an earlier response (resp_…) to continue from; it must have been stored.
- **Max Output Tokens · Optional**: Optional. The most tokens the answer (and the model's reasoning) may use. Empty is the model's own limit.
- **Reasoning Effort · Optional**: How much a reasoning model thinks before answering: less is faster and cheaper. Not every model takes every level. Options: Model default, None, Minimal, Low, Medium, High, Extra high, Max. Default: Model default.
- **Temperature · Optional**: Optional, 0–2. Lower is more focused, higher more varied. Reasoning models refuse it: leave it empty for them.
- **Store Response · Optional**: Keep the response at OpenAI (30 days) so a later step can continue from it. On by default.

### Classify Text for Violations

- **Text · Required**: The text to check.
- **Model · Optional**: Latest follows OpenAI's improvements; the snapshot gives the same verdicts over time. Options: Latest, Fixed snapshot (2024-09-26). Default: Latest.

### OpenAI › Image

### Analyze Image

- **Model · Optional**: The model that looks at the images. Default: gpt-6-luna.
- **Prompt · Optional**: What to ask about the images. Default: What's in this image?
- **Images From · Optional**: Links to images on the web, or image files from an earlier step. Options: Image URLs, Files. Default: Image URLs.
- **Image URLs · Required**: One or more public https links to images, comma or line separated. Shows when **Images From** is **Image URLs**.
- **Image Files · Required**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). PNG, JPEG, WEBP or non-animated GIF, up to 50 MB each. Shows when **Images From** is **Files**.
- **Detail · Optional**: How closely the model looks. Options: Auto, Low (faster, fewer tokens), High. Default: Auto.
- **JSON Schema · Required**: The shape of the answer, as JSON Schema, such as {"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}. Every property must be listed in required, and every object needs "additionalProperties": false. Shows when **File Format** is **jsonSchema**.
- **Schema Name · Optional**: A name for the schema (letters, digits, _ and -, up to 64). Default: result. Shows when **File Format** is **jsonSchema**.
- **Max Output Tokens · Optional**: Optional. The most tokens the answer (and the model's reasoning) may use. Empty is the model's own limit.
- **Reasoning Effort · Optional**: How much a reasoning model thinks before answering: less is faster and cheaper. Not every model takes every level. Options: Model default, None, Minimal, Low, Medium, High, Extra high, Max. Default: Model default.
- **Temperature · Optional**: Optional, 0–2. Lower is more focused, higher more varied. Reasoning models refuse it: leave it empty for them.

### Generate an Image

- **Model · Optional**: The image model. Default: gpt-image-2.5-flare.
- **Prompt · Required**: What the image should show, or what to change (up to 32,000 characters).
- **Number of Images · Optional**: 1 to 10. Large PNGs fill the 16 MB one step reads sooner: at 1536×1024, at most 3 PNG (2 transparent) or 7 JPEG/WEBP; at 1024×1024, 4 PNG or 10 JPEG/WEBP. Default: 1.
- **Size · Optional**: The image's size in pixels. Options: Auto, Square (1024×1024), Landscape (1536×1024), Portrait (1024×1536). Default: Auto.
- **Quality · Optional**: Higher quality takes longer and costs more. Options: Auto, Low, Medium, High. Default: Auto.
- **Background · Optional**: A transparent background needs PNG or WEBP. Options: Auto, Transparent, Opaque. Default: Auto.
- **File Format · Optional**: JPEG and WEBP are smaller. Options: PNG, JPEG, WEBP. Default: PNG.

### Edit Image

- **Model · Optional**: The image model. Default: gpt-image-2.5-flare.
- **Prompt · Required**: What the image should show, or what to change (up to 32,000 characters).
- **Images to Edit · Required**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). PNG, WEBP or JPG, under 50 MB each; up to 16.
- **Mask · Optional**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Optional. A PNG the size of the first image whose transparent areas mark where to edit.
- **Number of Images · Optional**: 1 to 10. Large PNGs fill the 16 MB one step reads sooner: at 1536×1024, at most 3 PNG (2 transparent) or 7 JPEG/WEBP; at 1024×1024, 4 PNG or 10 JPEG/WEBP. Default: 1.
- **Size · Optional**: The image's size in pixels. Options: Auto, Square (1024×1024), Landscape (1536×1024), Portrait (1024×1536). Default: Auto.
- **Quality · Optional**: Higher quality takes longer and costs more. Options: Auto, Low, Medium, High. Default: Auto.
- **Background · Optional**: A transparent background needs PNG or WEBP. Options: Auto, Transparent, Opaque. Default: Auto.
- **File Format · Optional**: JPEG and WEBP are smaller. Options: PNG, JPEG, WEBP. Default: PNG.

### OpenAI › Audio

### Generate Audio

- **Model · Optional**: The speech model. Default: gpt-4o-mini-tts.
- **Text · Required**: The text to speak (up to 4,096 characters).
- **Voice · Optional**: Marin and Cedar sound best. tts-1 and tts-1-hd have fewer voices. Options: Alloy to Verse (13 options). Default: Marin.
- **Voice Instructions · Optional**: Optional. How to speak: accent, emotion, pace, tone (not for tts-1 or tts-1-hd).
- **File Format · Optional**: The audio file's format. Options: MP3, Opus, AAC, FLAC, WAV, PCM (raw 24 kHz, 16-bit). Default: MP3.
- **Speed · Optional**: Optional, 0.25 to 4 (1 is normal).

### Transcribe a Recording

- **Audio File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV or WEBM, up to 25 MB.
- **Model · Optional**: The transcription model. Default: gpt-transcribe.
- **Language · Optional**: Optional. The spoken language as an ISO-639-1 code (en, de, fr …); faster and more accurate when given.
- **Prompt · Optional**: Optional. Words, names or style to guide the transcript (in the audio's language; English for a translation).
- **Output Format · Optional**: Subtitles and timestamps need whisper-1. Options: Text, Text with segments and timestamps (whisper-1), Plain text, SRT subtitles, WebVTT subtitles. Default: Text.
- **Temperature · Optional**: Optional, 0 to 1.

### Translate a Recording

- **Audio File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV or WEBM, up to 25 MB.
- **Prompt · Optional**: Optional. Words, names or style to guide the transcript (in the audio's language; English for a translation).
- **Output Format · Optional**: Subtitles and timestamps need whisper-1. Options: Text, Text with segments and timestamps (whisper-1), Plain text, SRT subtitles, WebVTT subtitles. Default: Text.
- **Temperature · Optional**: Optional, 0 to 1.

### OpenAI › File

### Upload a File

- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Up to 512 MB.
- **Purpose · Optional**: What the file is for. Options: User data (inputs to models), File search and code interpreter, Batch, Fine-tuning, Vision fine-tuning, Evals. Default: User data (inputs to models).
- **Delete After (days) · Optional**: Optional. OpenAI deletes the file this many days after the upload (1–30). Empty keeps it until deleted.

### List Files

- **Purpose · Optional**: Only files uploaded for this purpose. Options: Any, User data, File search and code interpreter, Batch, Fine-tuning, Vision fine-tuning, Evals. Default: Any.
- **Return All · Optional**: Read every file, page by page (at most 5000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many files to return (1–5000). Default: 50. Shows when **Return All** is off.

### Get a File and Delete a File

- **File ID · Required**: The file's id (file-…), as Upload a File or List Files returns it.

### OpenAI › Conversation

### Create

- **Opening Messages · Optional**: Optional. Up to 20 messages to start with, such as [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello!"}]. Roles: user, assistant, system, developer.
- **Metadata · Optional**: Optional on Create, required on Update: up to 16 text values to keep with the conversation, such as {"customer": "4711"}. Update replaces all of them.

### Get and Remove

- **Conversation ID · Required**: The conversation's id (conv_…).

### Update

- **Conversation ID · Required**: The conversation's id (conv_…).
- **Metadata · Optional**: Optional on Create, required on Update: up to 16 text values to keep with the conversation, such as {"customer": "4711"}. Update replaces all of them.

### OpenAI › Embedding

### Create

- **Model · Optional**: The embedding model. Default: text-embedding-3-small.
- **Text · Required**: The text to embed. To embed several at once, give a JSON list of texts, such as ["first", "second"] (up to 2,048).
- **Dimensions · Optional**: Optional. Shorter vectors (text-embedding-3 and later models only).

### OpenAI › Model

### List Models

- **ID Contains · Optional**: Optional. Only models whose id contains this text.

Source: https://docs.gorunner.io/apps/openai