Skip to content

FAQ

Jump to bottom
Amayyas edited this page Jul 6, 2026 · 2 revisions

FAQ - Frequently Asked Questions

Common questions about Flutter AI SDK.

General

What is Flutter AI SDK?

Flutter AI SDK is a unified Dart/Flutter wrapper for integrating multiple AI APIs (OpenAI, Anthropic, Google AI) with a single, consistent interface.

Which providers are supported?

  • OpenAI - GPT-5.5, GPT-5.4, GPT-5.4 mini/nano
  • Anthropic - Claude Opus 4.8, Sonnet 5, Haiku 4.5
  • Google AI - Gemini 3.5 Flash, Gemini 3.1 Pro/Flash-Lite

Is it free to use?

The SDK itself is open source and free. However, you need API keys from the respective providers, which have their own pricing.

Installation

How do I install the SDK?

Add to your pubspec.yaml:

dependencies:
  flutter_ai_sdk: ^1.0.0

Then run flutter pub get.

What are the minimum requirements?

  • Dart SDK: >=3.0.0 <4.0.0
  • Flutter: >=3.10.0

Does it work on all platforms?

Yes! Android, iOS, Web, macOS, Windows, and Linux are all supported.

API Keys

Where do I get API keys?

How do I securely store API keys?

Never commit API keys to version control. Options:

  • Environment variables
  • Flutter's --dart-define
  • Secure storage packages
  • Backend proxy
// Using dart-define
// Run: flutter run --dart-define=OPENAI_KEY=sk-...
const apiKey = String.fromEnvironment('OPENAI_KEY');

Usage

How do I switch between providers?

Simply change the provider parameter:

// OpenAI
final ai = FlutterAI(
  provider: AIProvider.openai,
  config: AIConfig(apiKey: openaiKey),
);

// Anthropic
final ai = FlutterAI(
  provider: AIProvider.anthropic,
  config: AIConfig(apiKey: anthropicKey),
);

// Google AI
final ai = FlutterAI(
  provider: AIProvider.googleAI,
  config: AIConfig(apiKey: googleKey),
);

How do I use streaming?

await for (final chunk in ai.streamChat('Tell me a story')) {
  if (chunk.isDelta) {
    print(chunk.delta);
  }
}

How do I send images?

final response = await ai.chatWithContent([
  const TextContent('What is in this image?'),
  const ImageContent.fromUrl('https://example.com/image.jpg'),
]);

How do I use function calling?

final tool = Tool(
  name: 'get_weather',
  description: 'Get weather for a location',
  parameters: ToolParameters(
    properties: {
      'location': ToolProperty.string(description: 'City name'),
    },
    required: ['location'],
  ),
);

final response = await ai.chatWithTools(
  'What is the weather in Paris?',
  tools: [tool],
);

Context & Conversations

How is context managed?

The SDK automatically maintains conversation history. Each message is added to the context for multi-turn conversations.

How do I clear the conversation?

ai.clearContext();

How do I access the conversation history?

final messages = ai.conversation.messages;
for (final msg in messages) {
  print('${msg.role}: ${msg.textContent}');
}

Can I disable context?

Yes, use addToContext: false:

final response = await ai.chat(
  'What is 2+2?',
  addToContext: false,
);

Errors

Why am I getting an authentication error?

  • Check your API key is correct
  • Ensure the key hasn't expired
  • Verify you have credits/quota available

Why am I getting rate limited?

You've exceeded the provider's rate limit. Wait and retry:

try {
  await ai.chat('Hello');
} on AIRateLimitError catch (e) {
  if (e.retryAfter != null) {
    await Future.delayed(e.retryAfter!);
    // Retry
  }
}

Why is my context too long?

Your conversation history exceeds the model's context window. Clear context:

try {
  await ai.chat(message);
} on AIContextLengthError {
  ai.clearContext();
  await ai.chat(message);
}

Models

What's the best model to use?

It depends on your use case:

Use Case Recommended
Complex reasoning GPT-5.5, Claude Opus 4.8
Fast responses GPT-5.4-mini, Claude Haiku 4.5, Gemini 3.5 Flash
Long documents Claude Opus 4.8, Gemini 3 (1M tokens)
Code generation GPT-5.5, Claude Sonnet 5
Cost-effective GPT-5.4-nano, Claude Haiku 4.5, Gemini 3.1 Flash-Lite

How do I specify a model?

final config = AIConfig(
  apiKey: 'your-key',
  model: 'gpt-5.5',
);

Performance

How can I reduce latency?

  1. Use streaming for perceived faster responses
  2. Use faster models (GPT-5.4-mini, Haiku, Flash)
  3. Reduce maxTokens when possible
  4. Use a region-close provider

How can I reduce costs?

  1. Use cost-effective models
  2. Limit maxTokens
  3. Clear context when appropriate
  4. Use token counting before requests

Debugging

How do I enable logging?

// Set log level
AILogger.level = LogLevel.verbose;

How do I see the raw API requests?

Enable verbose logging to see request/response details.

Other Questions

Can I use a proxy?

Yes, use baseUrl:

final config = AIConfig(
  apiKey: 'your-key',
  baseUrl: 'https://your-proxy.com/v1',
);

Can I add custom headers?

Yes:

final config = AIConfig(
  apiKey: 'your-key',
  headers: {
    'X-Custom-Header': 'value',
  },
);

How do I report a bug?

Open an issue on GitHub with:

  • SDK version
  • Flutter version
  • Provider used
  • Steps to reproduce
  • Error messages

Still have questions? Check the wiki or open a discussion.

Footer

📚 Flutter AI SDK Wiki | 💻 GitHub Repository | 🐛 Report Issue

Sidebar

Home

Getting Started

Core Concepts

Advanced Features

API Reference

Examples

Other

Clone this wiki locally