> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI

> This page outlines how to use the OpenAI integration for AI-powered actions in Cargo.

OpenAI provides advanced language models that power intelligent automation. Cargo's native integration with OpenAI allows you to use GPT models directly in your workflows for text generation, classification, summarization, and more.

## How to set up OpenAI

You can use OpenAI in two ways:

1. **Cargo credits** – Use OpenAI through Cargo's managed integration (no API key required)
2. **Your own API key** – Connect your OpenAI account for direct access

### Using Cargo credits

Select OpenAI from the node catalog and start using it immediately. Costs are deducted from your Cargo credits based on token usage.

### Using your own API key

To connect your OpenAI account:

| Field       | Description         |
| ----------- | ------------------- |
| **API Key** | Your OpenAI API key |

<Tip>
  Find your API key in the OpenAI platform under **API keys**.
</Tip>

***

## OpenAI actions

### Instruct

Send a prompt to an OpenAI model and receive a text response.

**Use cases**

* **Content generation** – Generate personalized emails, messages, or content
* **Classification** – Categorize text into predefined categories
* **Summarization** – Summarize long text into concise summaries
* **Data extraction** – Extract structured data from unstructured text
* **Translation** – Translate text between languages
* **Analysis** – Analyze sentiment, intent, or other text properties

**Configuration**

| Field               | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Model**           | Select the GPT model to use                             |
| **Prompt**          | The prompt to send to the model                         |
| **System prompt**   | Optional system instructions                            |
| **Maximum tokens**  | Limit output length (includes reasoning tokens)         |
| **Temperature**     | Control randomness (0 = deterministic, 2 = very random) |
| **With web search** | Enable web search capabilities for the agent            |
| **Response format** | Text, JSON object, or JSON schema                       |

### Available models

The available models — and their per-model credit costs — evolve with OpenAI's lineup, so the action's **Model** dropdown in the workspace is always the authoritative list. From the terminal:

```bash theme={null}
cargo-ai connection integration get openAi
```

**Picking a model:**

* **Flagship models** — complex reasoning, multi-step analysis, coding tasks
* **Mini variants** — the best cost/performance balance for most everyday tasks (start here)
* **Nano variants** — high-volume, low-stakes work: summarization, classification, simple extraction

### Response formats

Control how the model returns its response:

| Format          | Description                                       |
| --------------- | ------------------------------------------------- |
| **Text**        | Free-form text response (default)                 |
| **JSON object** | Response formatted as valid JSON                  |
| **JSON schema** | Response validated against a specific JSON schema |

<Tip>
  Use **JSON schema** when you need structured output with specific fields.
  Define your schema to ensure consistent, parseable responses.
</Tip>

#### Example JSON schema

```json theme={null}
{
  "type": "object",
  "properties": {
    "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
    "confidence": { "type": "number" },
    "summary": { "type": "string" }
  },
  "additionalProperties": false,
  "required": ["sentiment", "confidence", "summary"]
}
```

### Advanced settings

#### System prompt

Set instructions that guide the model's behavior across all prompts. Use system prompts to:

* Define the model's role or persona
* Set output format guidelines
* Provide context about your use case
* Establish constraints or rules

#### Temperature

Control the randomness of outputs:

| Temperature | Behavior                               |
| ----------- | -------------------------------------- |
| **0**       | Most deterministic, consistent outputs |
| **0.5-1**   | Balanced creativity and consistency    |
| **1-2**     | More creative, varied outputs          |

<Warning>
  For tasks requiring consistency (classification, extraction), use low
  temperature (0-0.3). For creative tasks (content generation), use higher
  temperature (0.7-1).
</Warning>

#### Web search

Enable the model to search the web for current information. Useful for:

* Real-time data lookups
* Current events or news
* Company or product research
* Fact verification