# How to Configure the Responses API for Reduced Token Consumption in UI-TARS

> Reduce token consumption with UI-TARS Responses API. Enable useResponsesApi: true and set max_tokens for efficient message handling and automatic pruning.

- Repository: [Bytedance Inc./UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop)
- Tags: performance
- Published: 2026-05-10

---

**Enable `useResponsesApi: true` and set a conservative `max_tokens` value to switch from Chat Completions to the Responses API, which sends only incremental messages and automatically prunes stale image responses to minimize token usage.**

The UI-TARS-desktop SDK provides a configurable bridge between OpenAI’s classic Chat Completions endpoint and the newer Responses API. When you configure the Responses API for reduced token consumption, the SDK adopts an incremental messaging protocol that transmits only conversation deltas, caps output length, and purges expired image contexts. This approach significantly lowers per-request costs while maintaining full conversational continuity.

## How the SDK Selects the API Endpoint

The SDK determines which endpoint to call based on the `useResponsesApi` boolean flag inside your model configuration. In [`packages/ui-tars/sdk/src/Model.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/Model.ts), the `invokeModelProvider` method branches at runtime:

```typescript
if (this.modelConfig.useResponsesApi) {
    // Build incremental inputs → openai.responses.create(...)
} else {
    // Fall back to openai.chat.completions.create(...)
}

```

When `useResponsesApi` is set to `true`, the SDK initiates three distinct token-saving mechanisms instead of mirroring the traditional chat completion flow.

## Three Mechanisms for Token Reduction

### Cap Generated Tokens with max_output_tokens

The Responses API respects the `max_output_tokens` parameter to limit the model’s generation length. In [`packages/ui-tars/sdk/src/Model.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/Model.ts) (lines 202‑209), the SDK automatically maps your `max_tokens` configuration value to `max_output_tokens` when the Responses API is active:

- Set `max_tokens` to the smallest value that satisfies your use case (e.g., 200–400 tokens)
- The SDK forwards this as `max_output_tokens` to the OpenAI Responses endpoint
- This hard cap prevents expensive over-generation on long-running conversations

### Send Only Incremental Messages

Instead of re-transmitting the entire conversation history on every turn, the SDK calculates the index of the last assistant message (`lastAssistantIndex`) and transmits only the new messages that follow it. This logic is implemented in [`packages/ui-tars/sdk/src/Model.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/Model.ts) (lines 46‑57) using the `convertToResponseApiInput` helper.

By sending deltas rather than the full context, you avoid paying for input tokens associated with previous turns that the model already processed.

### Prune Stale Image Responses Automatically

Image tokens are among the most expensive in LLM pricing. The SDK manages an image window via `headImageContext` and automatically deletes outdated image responses using `openai.responses.delete` (lines 61‑86 in [`packages/ui-tars/sdk/src/Model.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/Model.ts)). This cleanup ensures you do not accumulate token costs from base64-encoded images that have scrolled out of the active conversation window.

## Implementation Guide

### Enabling the Responses API in Model Configuration

Instantiate `UITarsModel` with `useResponsesApi: true` and a restrictive `max_tokens` budget:

```typescript
import { UITarsModel } from '@ui-tars/sdk';

const model = new UITarsModel({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://api.openai.com/v1',
  model: 'gpt-4o-mini',
  max_tokens: 300,            // Caps generated tokens
  useResponsesApi: true,      // Switches to Responses endpoint
});

await model.invoke({
  conversations: [{ role: 'user', content: 'What is the weather today?' }],
  images: [],
  screenContext: {},
  scaleFactor: 1,
  uiTarsVersion: 'V1_0',
});

```

### Persisting Settings in the Desktop Application

To store the preference for future runs, update the UI store located at [`apps/ui-tars/src/main/store/setting.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/store/setting.ts):

```typescript
import { setSetting } from '@/store/setting';

setSetting({ useResponsesApi: true });

```

The CLI entry point at [`packages/ui-tars/cli/src/cli/start.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/cli/src/cli/start.ts) defaults this value to `false`, so explicit configuration is required to opt into the token-saving behavior.

## Configuration Checklist for Minimal Token Use

- ✅ Set `useResponsesApi: true` in the model config or UI settings
- ✅ Choose a modest `max_tokens` value (200–400) that satisfies your response quality requirements
- ✅ Avoid sending large image payloads unless necessary; the SDK already resizes images to `MAX_PIXELS_*` constants
- ✅ Allow the SDK to handle stale image deletions automatically; no manual cleanup code is required

## Summary

Configuring the Responses API for reduced token consumption in UI-TARS requires three specific actions:

- Enable the `useResponsesApi` flag to switch from Chat Completions to the Responses endpoint
- Set a conservative `max_tokens` value, which the SDK maps to `max_output_tokens` to cap generation length
- Rely on the SDK’s incremental message logic and automatic image pruning to avoid paying for stale context or expired image tokens

## Frequently Asked Questions

### What is the difference between max_tokens and max_output_tokens in UI-TARS?

In the UI-TARS SDK, you configure `max_tokens` in your model settings, and the SDK translates this to `max_output_tokens` when calling the Responses API (as seen in [`packages/ui-tars/sdk/src/Model.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/Model.ts) lines 202‑209). The Responses API uses `max_output_tokens` as its parameter name, while Chat Completions uses `max_tokens`, but the SDK handles this mapping automatically.

### Does enabling useResponsesApi affect conversation history retention?

No. When `useResponsesApi` is enabled, the SDK still maintains full conversation history locally. However, it only sends the incremental delta of new messages to the API endpoint by identifying the `lastAssistantIndex` and using `convertToResponseApiInput`. This reduces input token costs without losing historical context.

### How does the automatic image cleanup work?

The SDK tracks an image window via `headImageContext` and calls `openai.responses.delete` on image responses that slide out of the active window (implemented in [`packages/ui-tars/sdk/src/Model.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/Model.ts) lines 61‑86). This prevents you from paying for base64 image tokens that are no longer relevant to the current conversation turn.

### Where is the Responses API setting stored in the desktop application?

The setting is stored in the Electron main process store at [`apps/ui-tars/src/main/store/setting.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/main/store/setting.ts). You can toggle it via the UI or programmatically using the `setSetting` function with `{ useResponsesApi: true }`. The CLI version defaults this to `false` in [`packages/ui-tars/cli/src/cli/start.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/cli/src/cli/start.ts).