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

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, the invokeModelProvider method branches at runtime:

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 (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 (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). 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:

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:

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

setSetting({ useResponsesApi: true });

The CLI entry point at 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 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}