OpenAI Dart Client

• Features
• Why choose this client?
• Quickstart
• Configuration
• Usage
  • Responses API
  • Other model APIs
  • Images, audio, and video
  • Files, batches, and model evaluation
  • Webhooks and safety
  • Advanced Responses workflows
  • Live and Realtime
  • Agents and Vaults
• Error Handling
• Examples
• API Coverage
• Official Documentation
• Sponsor
• License

OpenAIClient.fromEnvironment() reads OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID, and OPENAI_PROJECT_ID. It also reads optional OPENAI_WEBHOOK_SECRET for local verification. Environment loading is for native Dart; use explicit configuration when environment variables are unavailable.

OpenAIClient.withApiKey('YOUR_API_KEY') creates a client from a supplied key. Reuse a client for multiple requests and call close() when finished; an injected HTTP client remains caller-owned.

Use OpenAIConfig for a proxy, timeout, retry policy, or organization/project selection.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient(
    config: OpenAIConfig(
      authProvider: ApiKeyProvider('YOUR_API_KEY'),
      baseUrl: 'https://api.openai.com/v1',
      timeout: const Duration(minutes: 10),
      connectTimeout: const Duration(seconds: 30),
      retryPolicy: const RetryPolicy(maxRetries: 3),
      // organization: 'org-...',
      // project: 'proj-...',
    ),
  );

  try {
    final response = await client.responses.create(
      const CreateResponseRequest(
        model: 'gpt-5.5',
        input: ResponseInput.text('Hello!'),
      ),
    );
    print(response.outputText);
  } finally {
    client.close();
  }
}

For Azure, set the deployment URL and use AzureApiKeyProvider. See Error Handling for retry boundaries.

The main import is package:openai_dart/openai_dart.dart. Realtime uses package:openai_dart/openai_dart_realtime.dart; deprecated Assistants resources use package:openai_dart/openai_dart_assistants.dart.

Call client.responses.create with a model and input. Read the generated text with response.outputText and token usage with response.usage.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.responses.create(
      const CreateResponseRequest(
        model: 'gpt-5.5',
        input: ResponseInput.text('What is the capital of France?'),
      ),
    );
    print(response.outputText);
  } finally {
    client.close();
  }
}

→ Full example

Use client.responses.createStream and textDeltas() to display text as it arrives. Use the typed events or accumulate() when you also need tool calls and response metadata; collectText() consumes the stream into one string.

import 'dart:io';

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final stream = client.responses.createStream(
      const CreateResponseRequest(
        model: 'gpt-5.5',
        input: ResponseInput.text('Tell me a short story.'),
      ),
    );
    await for (final text in stream.textDeltas()) {
      stdout.write(text);
    }
  } finally {
    client.close();
  }
}

→ Full example

Pass the previous response ID with the next input. For separately managed conversation history, use client.conversations.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final first = await client.responses.create(
      const CreateResponseRequest(
        model: 'gpt-5.5',
        input: ResponseInput.text('My name is Alice.'),
      ),
    );
    final next = await client.responses.create(
      CreateResponseRequest(
        model: 'gpt-5.5',
        previousResponseId: first.id,
        input: const ResponseInput.text('What is my name?'),
      ),
    );
    print(next.outputText);
  } finally {
    client.close();
  }
}

→ Full example · Conversations example

Set TextConfig.format to JsonSchemaFormat to request output matching your schema. Check for refusals and incomplete responses before decoding the text.

import 'dart:convert';

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.responses.create(
      const CreateResponseRequest(
        model: 'gpt-5.5',
        input: ResponseInput.text('Extract the name from: Alice is a doctor.'),
        text: TextConfig(
          format: JsonSchemaFormat(
            name: 'person',
            strict: true,
            schema: {
              'type': 'object',
              'properties': {
                'name': {'type': 'string'},
              },
              'required': ['name'],
              'additionalProperties': false,
            },
          ),
        ),
      ),
    );
    if (response.status == ResponseStatus.completed &&
        response.outputText.isNotEmpty) {
      print(jsonDecode(response.outputText));
    }
  } finally {
    client.close();
  }
}

→ Responses example

Define a function with JSON Schema parameters. Your application executes the requested function and returns its result with the original callId; the client does not execute tools for you.

import 'dart:convert';

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.responses.create(
      CreateResponseRequest(
        model: 'gpt-5.5',
        input: const ResponseInput.text(
          'Use the add tool to calculate 123 + 456.',
        ),
        tools: [
          ResponseTool.function(
            name: 'add',
            description: 'Add two numbers',
            parameters: {
              'type': 'object',
              'properties': {
                'a': {'type': 'number'},
                'b': {'type': 'number'},
              },
              'required': ['a', 'b'],
              'additionalProperties': false,
            },
          ),
        ],
      ),
    );
    final results = <Item>[];
    for (final call in response.functionCalls) {
      if (call.name != 'add') throw StateError('Unknown tool: ${call.name}');
      final args = jsonDecode(call.arguments) as Map<String, dynamic>;
      final sum = (args['a'] as num) + (args['b'] as num);
      results.add(
        FunctionCallOutputItem.string(
          callId: call.callId,
          output: sum.toString(),
        ),
      );
    }
    if (results.isNotEmpty) {
      final finalResponse = await client.responses.create(
        CreateResponseRequest(
          model: 'gpt-5.5',
          previousResponseId: response.id,
          input: ResponseInput.items(results),
        ),
      );
      print(finalResponse.outputText);
    } else {
      print(response.outputText);
    }
  } finally {
    client.close();
  }
}

→ Responses example · Async tool results

Include text and image content in a Responses input message. Images can be supplied as a public URL, a data URL, or an uploaded file ID.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.responses.create(
      const CreateResponseRequest(
        model: 'gpt-5.5',
        input: ResponseInput.items([
          MessageItem(
            role: MessageRole.user,
            content: [
              InputContent.text('What is in this image?'),
              InputContent.imageUrl('https://example.com/image.jpg'),
            ],
          ),
        ]),
      ),
    );
    print(response.outputText);
  } finally {
    client.close();
  }
}

→ Full example · Chat vision example

Add ResponseTool.webSearch() to let the model search for current information. The full examples also show location hints, domain filters, sources, and image results.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.responses.create(
      CreateResponseRequest(
        model: 'gpt-5.5',
        input: const ResponseInput.text(
          'What are the latest developments in AI?',
        ),
        tools: [ResponseTool.webSearch()],
      ),
    );
    print(response.outputText);
  } finally {
    client.close();
  }
}

→ Full example · Search controls

Use client.responses.inputTokens.count to estimate input size before generating a response.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final count = await client.responses.inputTokens.count(
      model: 'gpt-5.5',
      input: const ResponseInput.text('Hello, how are you?'),
    );
    print(count.inputTokens);
  } finally {
    client.close();
  }
}

→ Full example

Use client.chat.completions.create for applications built around Chat messages. Read the first choice with response.text; new applications can start with the Responses examples above.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.chat.completions.create(
      ChatCompletionCreateRequest(
        model: 'gpt-5.5',
        messages: [
          ChatMessage.system('You are a helpful assistant.'),
          ChatMessage.user('What is the capital of France?'),
        ],
      ),
    );
    print(response.text);
  } finally {
    client.close();
  }
}

→ Full example

Use client.chat.completions.createStream with textDeltas() or ChatStreamAccumulator. Set StreamOptions(includeUsage: true) for final usage; the usage-only chunk can have no choices.

→ Full example

Use client.decisions.create for typed predicate, choice, and score questions. Answers can include refusals; input supports text and HTTP(S) or data URL images.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final decision = await client.decisions.create(
      DecisionRequest(
        model: 'gpt-6-luna',
        input: DecisionInput.text('The screen arrived broken.'),
        questions: [
          DecisionQuestion.predicate(
            name: 'damaged',
            instructions: 'Does the customer report a damaged item?',
          ),
        ],
      ),
    );
    for (final answer in decision.answers) {
      if (answer case PredicateDecisionAnswer(:final probability)) {
        print('Damage probability: $probability');
      } else if (answer is RefusalDecisionAnswer) {
        print('The question was refused.');
      }
    }
  } finally {
    client.close();
  }
}

→ Full example · Image input example

Use client.embeddings.create to generate text vectors. Set dimensions when you need a smaller vector.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.embeddings.create(
      EmbeddingRequest(
        model: 'text-embedding-3-small',
        input: EmbeddingInput.text('Hello, world!'),
        dimensions: 256,
      ),
    );
    print(response.firstEmbedding);
  } finally {
    client.close();
  }
}

→ Full example

Use client.images.generate or edit with an explicit model. Use editJson for URL, data URL, or file-ID inputs; generation and editing also have streaming variants.

import 'dart:convert';
import 'dart:io';

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final response = await client.images.generate(
      const ImageGenerationRequest(
        model: ImageModels.gptImage25Flare,
        prompt: 'A cute robot holding a flower',
        size: ImageSize.size1024x1024,
      ),
    );
    final image = response.data.first.b64Json;
    if (image != null) {
      await File('robot.png').writeAsBytes(base64Decode(image));
    }
  } finally {
    client.close();
  }
}

→ Full example · Model selection

Use client.audio.speech.create for speech bytes, createByteStream for audio chunks, and createStream for typed speech events. Transcription and translation are available through client.audio.transcriptions and client.audio.translations.

import 'dart:io';

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final bytes = await client.audio.speech.create(
      const SpeechRequest(
        model: 'gpt-4o-mini-tts',
        input: 'Hello! How are you today?',
        voice: SpeechVoice.marin,
        responseFormat: SpeechResponseFormat.mp3,
      ),
    );
    await File('speech.mp3').writeAsBytes(bytes);
  } finally {
    client.close();
  }
}

→ Full example · Streaming speech · Transcription and translation

Use client.videos.create to start a video job, poll retrieve until completion, then download with retrieveContent. The example also covers editing and extension.

→ Full example

Request Chat audio through client.chat.completions and choose a built-in or custom voice. Replay the returned audio ID in later messages; accumulate streamed audio before decoding it.

→ Full example

Use client.audio.voiceConsents to upload and manage consent recordings before creating custom voices.

→ Full example

Use client.audio.voices with a consent ID and an audio sample. Pass the returned voice ID to speech requests as a custom voice reference.

→ Full example

Use client.files to upload, list, retrieve, and delete files. Use client.uploads for large multipart uploads.

import 'dart:io';

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final file = await client.files.upload(
      bytes: await File('training.jsonl').readAsBytes(),
      filename: 'training.jsonl',
      purpose: FilePurpose.fineTune,
    );
    print(file.id);
  } finally {
    client.close();
  }
}

→ Full example · Large uploads

Use client.batches.create to submit a JSONL input file for asynchronous processing. Retrieve the batch status and output file when it completes.

→ Full example

Create a job through client.fineTuning.jobs with a training file ID, then retrieve its status and resulting model name.

→ Full example

Use client.evals to define grading criteria and run evaluations against test data.

→ Full example

Verify the original request bytes and headers with WebhookVerifier.unwrapBytes before reading an event. WebhookVerifier.fromEnvironment() reads OPENAI_WEBHOOK_SECRET without an API key; handle invalid signatures, acknowledge receipt, and deduplicate deliveries in your receiver.

→ Full example

Use client.webhooks to create, list, update, delete, rotate, and test project endpoints, and client.webhooks.eventTypes.list() to discover webhook event types. Save signing secrets returned by creation or rotation securely; test sends a real delivery.

→ Full example

Use client.moderations.create to check text against content policies.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final result = await client.moderations.create(
      ModerationRequest(input: ModerationInput.text('Check this text')),
    );
    print(result.results.first.flagged);
  } finally {
    client.close();
  }
}

→ Full example

Use client.safety.alerts for project alerts and client.safety.cases for organization cases. Retrieve IDs from verified notices using credentials for the correct scope.

→ Full example · Full example

Inspect typed monitoring details on HTTP exceptions, failed Responses, and WebSocket errors. These details describe the failure; they do not automatically resume work or execute suggested actions.

→ Full example

Use client.contentProvenanceChecks.create to inspect an image or audio file for C2PA and SynthID signals. Dispatch on the returned result type.

→ Full example

Use client.responses.connect() for a persistent connection with named response lanes. Continue with returned response IDs and await connection cleanup; browser connections require an authenticated backend proxy because WebSockets cannot send API-key headers.

import 'dart:io';

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final connection = await client.responses.connect();
    try {
      connection.create(
        const CreateResponseRequest(
          model: 'gpt-5.5',
          input: ResponseInput.text('Tell me a short joke.'),
        ),
      );
      await for (final message in connection.events) {
        if (message case ResponsesStreamEvent(
          event: OutputTextDeltaEvent(:final delta),
        )) {
          stdout.write(delta);
        } else if (message case ResponsesStreamEvent(
          event: ResponseCompletedEvent(),
        )) {
          break;
        } else if (message case ResponsesStreamEvent(
          event: ResponseFailedEvent() || ResponseIncompleteEvent(),
        )) {
          throw StateError('The response did not complete.');
        } else if (message is ResponsesErrorEvent) {
          throw StateError('Response failed: ${message.error.code}');
        }
      }
    } finally {
      await connection.close();
      await connection.done;
    }
  } finally {
    client.close();
  }
}

→ Full example

Use the steering controls to submit input during an active response. Respect pending continuation state so accepted input and completed tool results are not sent twice.

→ Full example

Opt into connection recovery and handle queued or unsent requests explicitly. Recovery reconnects the transport without automatically replaying frames already sent to the server.

→ Full example

Declare async tools and return results with their original call IDs. Continue from the latest response ID when concurrent jobs complete.

→ Full example

Return complete discovered function or custom-tool definitions with the original tool-search call ID. The example shows discovery and continuation without executing the tools.

→ Full example

Configure domain and content-type filters on ResponseTool.webSearch and request sources or image results. Search output is available through both ordinary Responses and streamed events.

→ Full example

Insert a ConfigurationUpdateItem before the next user input to change subsequent reasoning effort while preserving the request-level baseline. The full example covers replay and the supported compaction boundaries.

→ Full example

Use ResponsePromptCacheOptionsParam for Responses prewarming, TTL, and comparison diagnostics. Chat uses the narrower PromptCacheOptionsParam; returned usage counters report actual cached tokens.

→ Full example

Use client.containers to create a container with a memory tier and network policy, then pass its ID to Code Interpreter. See the migration guide for v11 configuration changes.

→ Full example

Configure a hosted shell through Responses tools, or execute local commands in your application and return their outputs. The client does not run local shell commands automatically.

→ Full example

Watch typed compaction events in the Responses stream. Progress events are nonterminal; preserve the complete returned compacted output for continuation.

→ Full example

Set access-program options explicitly when your account is eligible, and inspect the effective program returned by the service. Selection does not provision access or change account eligibility.

→ Full example

Use beta multi-agent injection to return tool results to the owning agent. Track acknowledgments and uncommitted results explicitly rather than rerunning tools after uncertain delivery.

→ Full example

Import openai_dart_realtime.dart for Realtime WebSocket and WebRTC sessions with audio events. Use client.realtimeSessions for ephemeral client secrets and WebRTC calls; your application owns capture, playback, and peer-connection setup.

import 'dart:io';

import 'package:openai_dart/openai_dart_realtime.dart' as realtime;

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final session = await client.realtime.connect(model: 'gpt-realtime-2');
    try {
      session.sendUserMessage('Say hello.', createResponse: false);
      session.createResponse(outputModalities: ['text']);
      await for (final event in session.events) {
        if (event is realtime.ResponseTextDeltaEvent) {
          stdout.write(event.delta);
        } else if (event is realtime.ResponseDoneEvent) {
          break;
        } else if (event is realtime.ErrorEvent) {
          throw StateError(event.error.message);
        }
      }
    } finally {
      await session.close();
    }
  } finally {
    client.close();
  }
}

→ Full example

Use client.live for WebRTC/SIP signaling, explicit call controls, and recordings. The full example also handles verified incoming-call notices.

→ Full example

Connect primary or sideband Live WebSockets to observe typed events and control a session. Your application handles media and tool delegation, and awaits graceful finalization.

→ Full example

Fork a stored Live session and use transcript helpers to group captions. The example covers inherited state and caller-owned channel cleanup.

→ Full example

Use client.agents to save reusable model, instruction, and tool configuration. Creating an agent stores configuration without starting a session; updates replace supplied fields, while clearX flags reset nullable fields.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    final agent = await client.agents.create(
      CreateAgentRequest(model: 'gpt-5.5', name: 'Research assistant'),
    );
    try {
      final updated = await client.agents.update(
        agent.id,
        UpdateAgentRequest(name: 'Updated research assistant'),
      );
      print(updated.name);
    } finally {
      await client.agents.delete(agent.id);
    }
  } finally {
    client.close();
  }
}

→ Full example

Use client.agents.sessions to create sessions, observe events, and submit function results or cancellation. Cancelling a local event subscription stops observation only; cancel durable work explicitly through session inputs.

→ Full example

Read session items, turns, and published OTLP traces through client.agents.sessions. Trace reads require organization export settings and permissions; a page contains only traces published when it is read.

→ Full example

Inspect child state and item/turn history through client.agents.sessions.subagents. These read-only methods do not create, resume, or interrupt child agents.

→ Full example

Use client.agents.environments and .templates to save hosted setup and prewarm eligible environments. Environment and session lifetimes are independent; deleting a template does not stop a session.

→ Full example

Use client.agents.environments.files for live workspace files and client.agents.sessions.artifacts for published outputs. Download artifacts to retain them before deleting a session; use downloadStream for incremental bytes.

→ Full example

Use client.vaults and .credentials to store or rotate OAuth, bearer, and hosted environment secrets. Credentials are write-only; deleting a stored credential does not revoke its provider token or cancel running work.

→ Full example

Catch typed exceptions such as RateLimitException, or ApiException for HTTP failures. OpenAIException also covers client and transport failures.

import 'package:openai_dart/openai_dart.dart';

Future<void> main() async {
  final client = OpenAIClient.fromEnvironment();

  try {
    await client.responses.create(
      const CreateResponseRequest(
        model: 'gpt-5.5',
        input: ResponseInput.text('Hello!'),
      ),
    );
  } on RateLimitException catch (error) {
    print('Rate limit: ${error.message}; retry hint: ${error.retryAfter}');
  } on ApiException catch (error) {
    print('HTTP ${error.statusCode}: ${error.message}');
  } on OpenAIException catch (error) {
    print('Client error: ${error.message}');
  } finally {
    client.close();
  }
}

Cloneable requests retry transient 429 responses; 5xx, timeout, and connection retries require an idempotent method. Billing/quota errors require action, and POST 5xx, multipart requests, and streams are not automatically replayed. Server retry hints are exposed as retryAfter; maxRetries: 0 disables automatic retries.

→ Full example · Retry and quota example

Some Responses tool/configuration details, Agents helper workflows, and administration APIs remain outside current coverage. See the API alignment inventory for the detailed scope.