Swift AI SDK

https://swift-ai-sdk-docs.vercel.app
Admin
Swift AI SDK is a unified AI toolkit for Apple platforms bringing Vercel AI SDK capabilities to iOS,...
Tokens:158,571
Snippets:1,166
Trust Score:7.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### Setup and Installation

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Instructions on how to add the OpenAI provider to your Swift package dependencies.

```APIDOC
## Setup and Installation

### Description
Add the OpenAI provider to your Swift package dependencies to utilize OpenAI's language model and embeddings APIs.

### Method
Package Dependency Management

### Endpoint
N/A

### Parameters
None

### Request Example
```swift
dependencies: [
    .package(url: "https://github.com/teunlao/swift-ai-sdk", from: "0.17.0")
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
            .product(name: "OpenAIProvider", package: "swift-ai-sdk")
        ]
    )
]
```

### Response
None
```

--------------------------------

### Generate Video from Image Prompt (Image-to-Video)

Source: https://swift-ai-sdk-docs.vercel.app/providers/klingai

This example demonstrates generating a video from a starting image and an optional text prompt. It also shows how to use the `imageTail` option for controlling the end frame. The 'pro' mode is often required for advanced features like `imageTail`.

```swift
import SwiftAISDK
import KlingAIProvider
import Foundation


let result = try await experimental_generateVideo(
  model: klingai.video("kling-v2.6-i2v"),
  prompt: .imageToVideo(
    image: .string("https://example.com/start-frame.png"),
    text: "The cat slowly turns its head and blinks"
  ),
  duration: 5,
  providerOptions: ["klingai": [
    // Pro mode required for start+end frame control (most models)
    "mode": "pro",
    // Optional: end frame image
    "imageTail": "https://example.com/end-frame.png"
  ]]
)


try result.video.data.write(to: URL(fileURLWithPath: "video.mp4"))
```

--------------------------------

### Replicate Provider Setup

Source: https://swift-ai-sdk-docs.vercel.app/providers/replicate

Instructions on how to add the Swift AI SDK and Replicate provider to your project using Swift Package Manager.

```APIDOC
## Setup

Add the library via Swift Package Manager and include these products:

```swift
// Package.swift (excerpt)
dependencies: [
  .package(url: "https://github.com/teunlao/swift-ai-sdk", from: "0.17.0")
],
targets: [
  .target(
    name: "YourTarget",
    dependencies: [
      .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
      .product(name: "ReplicateProvider", package: "swift-ai-sdk")
    ]
  )
]
```
```

--------------------------------

### Initialize SwiftPM Executable Project

Source: https://swift-ai-sdk-docs.vercel.app/getting-started/cli-quickstart

Initializes a new Swift Package Manager (SPM) executable project and navigates into the project directory. This sets up the basic structure for a command-line tool.

```bash
swift package init --type executable --name aicli
cd aicli
```

--------------------------------

### Provider Instance Creation

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Demonstrates how to create and configure an instance of the OpenAI provider, including default and customized setups.

```APIDOC
## Provider Instance Creation

### Description
Create an instance of the OpenAI provider. You can use the default instance which automatically uses the `OPENAI_API_KEY` environment variable, or create a customized instance with specific settings like API key, organization, and custom headers.

### Method
Provider Instantiation

### Endpoint
N/A

### Parameters
#### Query Parameters
- **baseURL** (string) - Optional - Use a different URL prefix for API calls.
- **apiKey** (string) - Optional - API key for authentication. Defaults to `OPENAI_API_KEY` environment variable.
- **name** (string) - Optional - The provider name. Defaults to `openai`.
- **organization** (string) - Optional - OpenAI Organization ID.
- **project** (string) - Optional - OpenAI Project ID.
- **headers** ([String: String]) - Optional - Custom headers to include in requests.
- **fetch** (FetchFunction) - Optional - Custom fetch implementation.

### Request Example
**Default Instance:**
```swift
import SwiftAISDK
import OpenAIProvider

// Uses OPENAI_API_KEY environment variable automatically
let model = openai("gpt-4o")
```

**Customized Instance:**
```swift
import OpenAIProvider

let provider = createOpenAIProvider(
    OpenAIProviderSettings(
        apiKey: "sk-...",
        organization: "org-...",
        headers: ["Custom-Header": "value"]
    )
)

let model = provider("gpt-4o")
```

### Response
- **model** (LanguageModel) - An instance of the language model configured with the specified settings.
```

--------------------------------

### Guide Tool Usage with Instructions (Swift)

Source: https://swift-ai-sdk-docs.vercel.app/agents/building-agents

Instructs an agent on how to effectively use available tools, such as a research assistant using web search and document analysis. It outlines a step-by-step process for research tasks.

```swift
let researchAgent = Agent<Never, Never>(settings: .init(
  model: .v3(openai("gpt-4o")),
  system: """
You are a research assistant with access to search and document tools.


When researching:
1. Always start with a broad search to understand the topic
2. Use document analysis for detailed information
3. Cross-reference multiple sources before drawing conclusions
4. Cite your sources when presenting information
5. If information conflicts, present both viewpoints
""",
  tools: [
    "webSearch": webSearch,
    "analyzeDocument": analyzeDocument,
    "extractQuotes": extractQuotes
  ]
))
```

--------------------------------

### Configure Swift Package Dependencies

Source: https://swift-ai-sdk-docs.vercel.app/getting-started/cli-quickstart

Defines the package's metadata, including its name, supported platforms, and dependencies. It specifies the Swift AI SDK and the OpenAIProvider as products required for the executable target.

```swift
import PackageDescription


let package = Package(
  name: "aicli",
  platforms: [.macOS(.v13)],
  dependencies: [
    .package(url: "https://github.com/teunlao/swift-ai-sdk", branch: "main")
  ],
  targets: [
    .executableTarget(
      name: "aicli",
      dependencies: [
        .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
        .product(name: "OpenAIProvider", package: "swift-ai-sdk")
      ]
    )
  ]
)
```

--------------------------------

### Configure Per-Request Custom Metadata in Swift

Source: https://swift-ai-sdk-docs.vercel.app/ai-sdk-core/middleware

This Swift example illustrates how to add and access custom metadata for individual requests using `providerOptions`. The `yourLogMiddleware` function demonstrates accessing this metadata, which can be useful for logging or debugging purposes. The example shows passing metadata like `["hello": "world"]` to the `generateText` call.

```swift
import SwiftAISDK
import OpenAIProvider


func yourLogMiddleware() -> LanguageModelV3Middleware {
  LanguageModelV3Middleware(
    wrapGenerate: { doGenerate, _, params, _ in
      if let metadata = params.providerOptions?["yourLogMiddleware"] {
        print("METADATA", metadata)
      }
      let result = try await doGenerate()
      return result
    }
  )
}


let result = try await generateText(
  model: wrapLanguageModel(
    model: openai("gpt-4o"),
    middleware: .single(yourLogMiddleware())
  ),
  prompt: "Invent a new holiday and describe its traditions.",
  providerOptions: ["yourLogMiddleware": ["hello": "world"]]
)


print(result.text)

```

--------------------------------

### Configure Vapor Project Dependencies (Package.swift)

Source: https://swift-ai-sdk-docs.vercel.app/getting-started/server-vapor-quickstart

Defines the project dependencies for a Vapor application, including the Vapor framework itself and the Swift AI SDK with OpenAI provider. It specifies the platform and target configurations.

```swift
import PackageDescription


let package = Package(
  name: "AIService",
  platforms: [.macOS(.v13)],
  dependencies: [
    .package(url: "https://github.com/vapor/vapor", from: "4.96.0"),
    .package(url: "https://github.com/teunlao/swift-ai-sdk", branch: "main")
  ],
  targets: [
    .executableTarget(
      name: "AIService",
      dependencies: [
        .product(name: "Vapor", package: "vapor"),
        .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
        .product(name: "OpenAIProvider", package: "swift-ai-sdk")
      ]
    )
  ]
)

```

--------------------------------

### Model-specific Options

Source: https://swift-ai-sdk-docs.vercel.app/providers/replicate

Example demonstrating how to pass model-specific options to the Replicate provider for fine-tuning image generation.

```APIDOC
### Model-specific options

```swift
let result = try await generateImage(
  model: replicate.image("recraft-ai/recraft-v3"),
  prompt: "The Loch Ness Monster getting a manicure",
  size: "1365x1024",
  providerOptions: [
    "replicate": ["style": .string("realistic_image")]
  ]
)
```
```

--------------------------------

### Open Responses Provider Setup

Source: https://swift-ai-sdk-docs.vercel.app/providers/open-responses

Instructions on how to add the Open Responses provider to your Swift package dependencies.

```APIDOC
## Swift Package Setup

### Description
Add the `SwiftAISDK` and `OpenResponsesProvider` to your project's dependencies in `Package.swift`.

### Method
Package Dependency Management

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
// Package.swift (excerpt)
dependencies: [
  .package(url: "https://github.com/teunlao/swift-ai-sdk", from: "0.17.0")
],
targets: [
  .target(
    name: "YourTarget",
    dependencies: [
      .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
      .product(name: "OpenResponsesProvider", package: "swift-ai-sdk")
    ]
  )
]
```

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Generate Image with OpenAI Provider Options in Swift

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Provides an example of generating an image using the OpenAI provider, demonstrating the use of `providerOptions` such as `quality`. It also shows how to access the generated image and metadata.

```swift
let result = try await generateImage(
  model: openai.image("gpt-image-1"),
  prompt: "A salamander at sunrise in a forest pond in the Seychelles.",
  providerOptions: [
    "openai": ["quality": "high"]
  ]
)
let image = result.image
let providerMetadata = result.providerMetadata
```

--------------------------------

### Image Generation with Replicate

Source: https://swift-ai-sdk-docs.vercel.app/providers/replicate

Basic usage example for generating images using the Replicate provider, including prompt and aspect ratio parameters.

```APIDOC
## Image Models

You can create Replicate image models using the `.image()` factory method. For more on image generation with the AI SDK see `generateImage`.
> Note: Model support for `size` and other parameters varies by model. Check the model’s documentation on Replicate for supported options and additional parameters that can be passed via `providerOptions.replicate`.

### Basic Usage

```swift
import SwiftAISDK
import ReplicateProvider
import Foundation


let result = try await generateImage(
  model: replicate.image("black-forest-labs/flux-schnell"),
  prompt: "The Loch Ness Monster getting a manicure",
  aspectRatio: "16:9"
)


if case let .binary(images) = result.images, let first = images.first {
  try first.write(to: URL(fileURLWithPath: "image.webp"))
}
```
```

--------------------------------

### Setup Prodia Provider in Swift

Source: https://swift-ai-sdk-docs.vercel.app/providers/prodia

This code snippet demonstrates how to add the Prodia provider to your Swift package dependencies. It involves specifying the package URL and the necessary dependencies for your target.

```swift
// Package.swift (excerpt)
dependencies: [
  .package(url: "https://github.com/teunlao/swift-ai-sdk", from: "0.17.0")
],
targets: [
  .target(
    name: "YourTarget",
    dependencies: [
      .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
      .product(name: "ProdiaProvider", package: "swift-ai-sdk")
    ]
  )
]
```

--------------------------------

### Swift Package Manager Setup for Replicate

Source: https://swift-ai-sdk-docs.vercel.app/providers/replicate

Integrates the Swift AI SDK with Replicate provider support using Swift Package Manager. Ensure to include both 'SwiftAISDK' and 'ReplicateProvider' products in your target's dependencies.

```swift
// Package.swift (excerpt)
dependencies: [
  .package(url: "https://github.com/teunlao/swift-ai-sdk", from: "0.17.0")
],
targets: [
  .target(
    name: "YourTarget",
    dependencies: [
      .product(name: "SwiftAISDK", package: "swift-ai-sdk"),
      .product(name: "ReplicateProvider", package: "swift-ai-sdk")
    ]
  )
]
```

--------------------------------

### Enable Reasoning with Anthropic Models

Source: https://swift-ai-sdk-docs.vercel.app/providers/anthropic

This example demonstrates how to enable and configure reasoning for specific Anthropic models using the `providerOptions`. It shows how to set a thinking budget and access the reasoning output.

```swift
import SwiftAISDK
import AnthropicProvider


let result = try await generateText(
  model: anthropic("claude-opus-4-20250514"),
  prompt: "How many people will live in the world in 2040?",
  providerOptions: [
    "anthropic": [
      "thinking": ["type": "enabled", "budgetTokens": 12000]
    ]
  ]
)


print(result.reasoning) // reasoning text
print(result.reasoningDetails) // reasoning details including redacted reasoning
print(result.text) // text response
```

--------------------------------

### Basic Image Generation with Replicate

Source: https://swift-ai-sdk-docs.vercel.app/providers/replicate

Generates an image using a specified Replicate model and prompt. This example demonstrates basic usage with the 'generateImage' function and handles the result, saving the first image if available.

```swift
import SwiftAISDK
import ReplicateProvider
import Foundation


let result = try await generateImage(
  model: replicate.image("black-forest-labs/flux-schnell"),
  prompt: "The Loch Ness Monster getting a manicure",
  aspectRatio: "16:9"
)


if case let .binary(images) = result.images, let first = images.first {
  try first.write(to: URL(fileURLWithPath: "image.webp"))
}
```

--------------------------------

### Respond to UI Messages on Server (Swift)

Source: https://swift-ai-sdk-docs.vercel.app/agents/building-agents

Provides a conceptual example of using the `respond()` method on the server to generate a UI message stream response. It notes the possibility of piping this stream to an HTTP response.

```swift
// Example concept for a server route handler
let response = try myAgent.respond(messages: uiMessages)
// Pipe to an HTTP response using `pipeUIMessageStreamToResponse` if desired
```

--------------------------------

### Default Replicate Provider Instance

Source: https://swift-ai-sdk-docs.vercel.app/providers/replicate

Imports and uses the default Replicate provider instance. This is a convenient way to get started without explicit configuration.

```swift
import ReplicateProvider


let model = replicate.image("black-forest-labs/flux-schnell")
```

--------------------------------

### Instantiate Default ByteDance Provider

Source: https://swift-ai-sdk-docs.vercel.app/providers/bytedance

Imports and uses the default `byteDance` provider instance for video generation. This is the simplest way to get started with the provider.

```swift
import SwiftAISDK
import ByteDanceProvider


let model = byteDance.video("seedance-1-0-pro-250528")
```

--------------------------------

### Import and Use Default Rev.ai Transcription Provider

Source: https://swift-ai-sdk-docs.vercel.app/providers/revai

Demonstrates importing the default Rev.ai provider instance and creating a transcription model. This is the simplest way to get started with Rev.ai transcription.

```swift
import SwiftAISDK
import RevAIProvider


let model = revai.transcription("machine")
```

--------------------------------

### Run Swift AI CLI with OpenAI API Key

Source: https://swift-ai-sdk-docs.vercel.app/getting-started/cli-quickstart

Executes the Swift CLI application, providing the OpenAI API key as an environment variable and passing a prompt as a command-line argument. This demonstrates how to interact with the AI model via the CLI.

```bash
OPENAI_API_KEY=sk-... swift run aicli "Write a limerick about SwiftPM"
```

--------------------------------

### Create Default Moonshot AI Provider Instance

Source: https://swift-ai-sdk-docs.vercel.app/providers/moonshotai

Imports the default Moonshot AI provider instance named 'moonshotai'. This is the simplest way to get started if you have the MOONSHOT_API_KEY environment variable set.

```swift
import MoonshotAIProvider
```

--------------------------------

### Create Default Vercel Provider Instance

Source: https://swift-ai-sdk-docs.vercel.app/providers/vercel

This Swift code demonstrates how to import and use the default Vercel provider instance named 'vercel'. It's a straightforward way to get started with the Vercel API.

```swift
import SwiftAISDK
import VercelProvider


let model = vercel("v0-1.5-md")
```

--------------------------------

### Implement Swift CLI for AI Text Streaming

Source: https://swift-ai-sdk-docs.vercel.app/getting-started/cli-quickstart

The main executable file for the CLI tool. It parses command-line arguments for a prompt, calls the Swift AI SDK to stream text from an OpenAI model, and prints the response to the terminal. Error handling is included for API calls and missing prompts.

```swift
import Foundation
import SwiftAISDK
import OpenAIProvider


@main struct App {
  static func main() async {
    let prompt = CommandLine.arguments.dropFirst().joined(separator: " ")
    guard !prompt.isEmpty else {
      print("Usage: aicli <prompt>")
      return
    }
    do {
      let stream = try streamText(model: openai("gpt-4o"), prompt: prompt)
      for try await delta in stream.textStream { print(delta, terminator: "") }
      print()
    } catch { fputs("Error: (error)\n", stderr) }
  }
}
```

--------------------------------

### Import and Use Default Anthropic Provider Instance

Source: https://swift-ai-sdk-docs.vercel.app/providers/anthropic

Demonstrates how to import the default Anthropic provider and create a model instance using the global `anthropic` function. This is the simplest way to get started.

```swift
import AnthropicProvider


// Use the global anthropic instance
let model = anthropic("claude-3-haiku-20240307")
```

--------------------------------

### Generate Video from Image and Text with ByteDance

Source: https://swift-ai-sdk-docs.vercel.app/providers/bytedance

Creates a video from a first-frame image and an optional text prompt using the ByteDance provider. This is useful for scenarios where you want to guide the video generation with a starting visual.

```swift
import SwiftAISDK
import ByteDanceProvider
import Foundation


let result = try await experimental_generateVideo(
  model: byteDance.video("seedance-1-5-pro-251215"),
  prompt: .imageToVideo(
    image: .string("https://example.com/first-frame.png"),
    text: "The cat slowly turns its head and blinks"
  ),
  duration: 5,
  providerOptions: ["bytedance": [
    "watermark": false
  ]]
)


try result.video.data.write(to: URL(fileURLWithPath: "video.mp4"))
```

--------------------------------

### Generate Text with System Prompt for Guided Responses

Source: https://swift-ai-sdk-docs.vercel.app/foundations/prompts

Illustrates how to use a system prompt to guide the AI's behavior and constrain its responses, in addition to a regular prompt. This is useful for setting the AI's persona or task.

```swift
import SwiftAISDK
import OpenAIProvider


let destination = "Kyoto"
let lengthOfStay = 5


let result = try await generateText(
  model: openai("gpt-4o"),
  system: "You help planning travel itineraries. Respond to the users' request with a list of the best stops to make in their destination.",
  prompt: "I am planning a trip to \(destination) for \(lengthOfStay) days. " +
          "Please suggest the best tourist activities for me to do."
)
print(result.text)
```

--------------------------------

### Implement Streaming SSE Route (Vapor)

Source: https://swift-ai-sdk-docs.vercel.app/getting-started/server-vapor-quickstart

Sets up a streaming endpoint in a Vapor application that uses the Swift AI SDK to generate text responses. It handles incoming queries and streams the AI-generated content as Server-Sent Events (SSE).

```swift
import Vapor
import SwiftAISDK
import OpenAIProvider


func routes(_ app: Application) throws {
  app.get("stream") { req async throws -> Response in
    let stream = try streamText(
      model: openai("gpt-4o"),
      prompt: req.query[String.self, at: "q"] ?? "Hello"
    )


    let sse = makeStreamTextSSEStream(stream.fullStream, includeUsage: false)


    let res = Response(status: .ok)
    res.headers.replaceOrAdd(name: .contentType, value: "text/event-stream")


    // Pipe chunks
    for try await line in sse {
      try await res.body.write(.init(string: "data: \(line)\n\n"))
      try await res.body.flush()
    }
    return res
  }
}

```

--------------------------------

### Use Descriptive Property Names with Zod

Source: https://swift-ai-sdk-docs.vercel.app/zod-adapter/overview

Demonstrates how to use clear and descriptive property names in Zod schemas for better readability. This improves maintainability by making the schema's intent obvious. It contrasts a bad example with short, unclear names to a good example with self-explanatory names.

```typescript
// ❌ Bad
z.object([
  "d": z.string(),
  "t": z.number()
])


// ✅ Good
z.object([
  "destination": z.string(),
  "travelTime": z.number()
])
```

--------------------------------

### Text-to-Video Generation with Alibaba

Source: https://swift-ai-sdk-docs.vercel.app/providers/alibaba

Generates a video from a text prompt using Alibaba's video models via the Swift AI SDK. This example shows how to specify model, prompt, resolution, duration, and provider-specific options like prompt extension and polling timeout.

```swift
import SwiftAISDK
import AlibabaProvider
import Foundation


let result = try await experimental_generateVideo(
  model: alibaba.video("wan2.6-t2v"),
  prompt: "A serene mountain lake at sunset with gentle ripples on the water.",
  resolution: "1280x720",
  duration: 5,
  providerOptions: [
    "alibaba": [
      "promptExtend": true,
      "pollTimeoutMs": 600_000 // 10 minutes
    ]
  ]
)

try result.video.data.write(to: URL(fileURLWithPath: "video.mp4"))
```

--------------------------------

### Sequential Processing Example in Swift

Source: https://swift-ai-sdk-docs.vercel.app/agents/workflows

Demonstrates sequential processing by generating marketing copy and then evaluating its quality. It uses the Swift AI SDK with OpenAIProvider. The process involves multiple LLM calls, with the output of one serving as the input for the next. It includes error handling and quality checks for the generated copy.

```swift
import SwiftAISDK
import OpenAIProvider


struct MarketingQuality: Codable, Sendable {
  let hasCallToAction: Bool
  let emotionalAppeal: Int
  let clarity: Int
}


struct MarketingResult: Sendable {
  let copy: String
  let quality: MarketingQuality
}


func generateMarketingCopy(_ input: String) async throws -> MarketingResult {
  let copy = try await generateText(
    model: openai("gpt-4o"),
    prompt: "Write persuasive marketing copy for: \(input). Focus on benefits and emotional appeal."
  ).text


  let quality = try await generateText(
    model: openai("gpt-4o"),
    experimentalOutput: Output.object(MarketingQuality.self, name: "quality_check"),
    prompt: """Evaluate this marketing copy for:
    1. Presence of call to action (true/false)
    2. Emotional appeal (1-10)
    3. Clarity (1-10)


    Copy to evaluate: \(copy)
    """
  ).experimentalOutput


  if !quality.hasCallToAction || quality.emotionalAppeal < 7 || quality.clarity < 7 {
    let improved = try await generateText(
      model: openai("gpt-4o"),
      prompt: "Rewrite this marketing copy with a clear CTA, stronger emotional appeal, and improved clarity. Original: \(copy)"
    )
    return .init(copy: improved.text, quality: quality)
  }


  return .init(copy: copy, quality: quality)
}
```

--------------------------------

### Image-to-Video Generation with Alibaba

Source: https://swift-ai-sdk-docs.vercel.app/providers/alibaba

Creates a video from an initial image and an optional text prompt using Alibaba's video models and the Swift AI SDK. This example includes loading image data and configuring provider options for polling timeout.

```swift
import SwiftAISDK
import AlibabaProvider
import AISDKProviderUtils
import Foundation


let imageData = try Data(contentsOf: URL(string: "https://example.com/landscape.jpg")!)


let result = try await experimental_generateVideo(
  model: alibaba.video("wan2.6-i2v"),
  prompt: .imageToVideo(
    image: .data(imageData),
    text: "Camera slowly pans across the landscape"
  ),
  duration: 5,
  providerOptions: [
    "alibaba": [
      "pollTimeoutMs": 600_000 // 10 minutes
    ]
  ]
)

try result.video.data.write(to: URL(fileURLWithPath: "video.mp4"))
```

--------------------------------

### Create a Basic Agent in Swift

Source: https://swift-ai-sdk-docs.vercel.app/agents/building-agents

Instantiate the Swift Agent with basic model and system prompt configuration. This sets up the core agent with a specified language model and initial instructions.

```swift
import SwiftAISDK
import OpenAIProvider


let myAgent = Agent<Never, Never>(settings: .init(
  model: .v3(openai("gpt-4o")),
  system: "You are a helpful assistant.",
  tools: [:]
))
```

--------------------------------

### Language Model Usage

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Explains how to create language models using the OpenAI provider and provides an example of generating text.

```APIDOC
## Language Model Usage

### Description
Invoke the OpenAI provider instance as a function to create a language model. You can specify the model ID and optionally pass additional settings or explicitly select the API (responses, chat, or completion).

### Method
Language Model Creation and Text Generation

### Endpoint
N/A

### Parameters
#### Path Parameters
- **modelId** (string) - Required - The identifier of the language model (e.g., "gpt-5").
- **additionalSettings** (Any) - Optional - Additional settings specific to the chosen API.

### Request Example
**Creating a model:**
```swift
let model = openai("gpt-5")

// With additional settings
let modelWithOptions = openai("gpt-5", /* additional settings */)
```

**Generating Text:**
```swift
import SwiftAISDK
import OpenAIProvider

let result = try await generateText(
  model: openai("gpt-5"),
  prompt: "Write a vegetarian lasagna recipe for 4 people."
)

print(result.text)
```

### Response
#### Success Response (200)
- **text** (string) - The generated text output from the language model.

#### Response Example
```json
{
  "text": "A detailed vegetarian lasagna recipe..."
}
```
```

--------------------------------

### Create Basic Tool in Swift

Source: https://swift-ai-sdk-docs.vercel.app/foundations/tools

Demonstrates the creation of a basic tool in Swift using the `tool` function. This tool fetches weather information based on a city and unit, returning a `WeatherReport`. It uses Codable structs for input and output, and an async closure to perform the tool's action.

```Swift
import SwiftAISDK
import OpenAIProvider


struct WeatherQuery: Codable, Sendable {
  let city: String
  let unit: String
}


struct WeatherReport: Codable, Sendable {
  let city: String
  let temperature: Double
  let unit: String
}


let getWeather = tool(
  description: "Fetch current weather by city",
  inputSchema: WeatherQuery.self
) { query, _ in
  // ... fetch weather for `query.city` (omitted)
  WeatherReport(city: query.city, temperature: 21, unit: query.unit)
}
```

--------------------------------

### Initialize OpenAI Image Generation Model in Swift

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Illustrates how to instantiate an OpenAI image generation model using the `.image()` factory method. This prepares the SDK for image creation requests.

```swift
let model = openai.image("dall-e-3")
```

--------------------------------

### Prompt Caching with Alibaba Models

Source: https://swift-ai-sdk-docs.vercel.app/providers/alibaba

Explains how to leverage both implicit and explicit prompt caching mechanisms provided by Alibaba models to optimize costs for repeated prompts.

```APIDOC
## POST /generateText (Prompt Caching)

### Description
Alibaba models support prompt caching to reduce costs for repeated prompts. This section covers both automatic implicit caching and manual explicit caching using `cacheControl`.

### Method
POST

### Endpoint
/generateText

### Parameters
#### Query Parameters
- **model** (string) - Required - The Alibaba model to use (e.g., "qwen-plus").
- **messages** (array) - Required - An array of message objects, where individual messages can have `providerOptions` for cache control.

### Request Body
(Not applicable for this example, parameters are passed directly)

### Request Example (Single Message Cache Control)
```swift
import SwiftAISDK
import AlibabaProvider
import AISDKProviderUtils


let result = try await generateText(
  model: alibaba("qwen-plus"),
  messages: [
    .system(SystemModelMessage(
      content: "You are a helpful assistant. [... long system prompt ... ]",
      providerOptions: [
        "alibaba": [
          "cacheControl": ["type": "ephemeral"]
        ]
      ]
    ))
  ]
)
print(result.text)
```

### Request Example (Multi-part Message Cache Control)
```swift
import SwiftAISDK
import AlibabaProvider
import AISDKProviderUtils


let longDocument = "... large document content ..."


let result = try await generateText(
  model: alibaba("qwen-plus"),
  messages: [
    .user(UserModelMessage(content: .parts([
      .text(TextPart(text: "Context: Please analyze this document.")),
      .text(TextPart(
        text: longDocument,
        providerOptions: [
          "alibaba": [
            "cacheControl": ["type": "ephemeral"]
          ]
        ]
      ))
    ])))
  ]
)
print(result.text)
```

**Note:** The minimum content length for a cache block is 1,024 tokens.

### Response
#### Success Response (200)
- **text** (string) - The generated text response from the model.

#### Response Example
```json
{
  "text": "The analysis of the document is as follows..."
}
```
```

--------------------------------

### Initialize OpenAI Completion Model in Swift

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Demonstrates how to create a model instance for calling the OpenAI completions API using the `.completion()` factory method in Swift. Currently supports `gpt-3.5-turbo-instruct`.

```swift
let model = openai.completion("gpt-3.5-turbo-instruct")
```

--------------------------------

### Transcribe Audio with Default Options

Source: https://swift-ai-sdk-docs.vercel.app/providers/fal

Creates a transcription model using the Fal API with the 'wizper' model ID. This is a basic setup for audio transcription.

```swift
let model = fal.transcription("wizper")
```

--------------------------------

### Import and Use Alibaba Provider in Swift

Source: https://swift-ai-sdk-docs.vercel.app/foundations/providers-and-models

Provides an example of importing the Alibaba provider module and accessing its language models via the global shortcut or a factory function, with environment variable-based API key loading.

```swift
import AlibabaProvider

// Using the global shortcut
let alibabaModel = alibaba("qwen-plus")

// Using the factory for advanced configuration
let customAlibabaProvider = createAlibaba(settings: AlibabaProviderSettings(...))

```

--------------------------------

### Configure OpenAI Completion Model Settings in Swift

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Provides an example of how to pass model-specific settings, such as `echo`, `logitBias`, `suffix`, and `user`, when generating text with OpenAI completion models in Swift.

```swift
let model = openai.completion("gpt-3.5-turbo-instruct")


try await model.doGenerate(
  providerOptions: [
    "openai": [
      "echo": true, // optional, echo the prompt in addition to the completion
      "logitBias": [
        // optional likelihood for specific tokens
        "50256": -100
      ],
      "suffix": "some text", // optional suffix that comes after a completion of inserted text
      "user": "test-user" // optional unique user identifier
    ]
  ]
)
```

--------------------------------

### Import and Use OpenAI Provider in Swift

Source: https://swift-ai-sdk-docs.vercel.app/foundations/providers-and-models

Demonstrates how to import the OpenAI provider module and use its global shortcut or factory function to create a language model instance. It highlights lazy API key loading from environment variables.

```swift
import OpenAIProvider

// Using the global shortcut
let openaiModel = openai("gpt-4o")

// Using the factory for advanced configuration
let customOpenAIProvider = createOpenAIProvider(settings: OpenAIProviderSettings(...))

```

--------------------------------

### Handle NoTranscriptGeneratedError in Swift

Source: https://swift-ai-sdk-docs.vercel.app/ai-sdk-core/transcription

Provides an example of how to catch and handle the `NoTranscriptGeneratedError` that occurs when transcription fails. It shows how to access the error's `cause` and `responses` properties for debugging.

```swift
import SwiftAISDK
import OpenAIProvider


let audioData = try Data(contentsOf: URL(fileURLWithPath: "audio.mp3"))


do {
  _ = try await transcribe(
    model: openai.transcription("whisper-1"),
    audio: .data(audioData)
  )
} catch let error as NoTranscriptGeneratedError {
  print("NoTranscriptGeneratedError")
  print("Cause:", error.cause ?? "none")
  print("Responses:", error.responses)
}
```

--------------------------------

### Handle InvalidArgumentError in Swift

Source: https://swift-ai-sdk-docs.vercel.app/ai-sdk-core/error-handling

Shows how to catch and handle `InvalidArgumentError`, which is raised when the input parameters to an SDK function are invalid. The example demonstrates accessing the error message for debugging.

```swift
do {
  let result = try await generateText(
    model: openai("gpt-4o"),
    prompt: "",  // Empty prompt
    maxOutputTokens: -1  // Invalid token count
  )
} catch let error as InvalidArgumentError {
  print("Invalid argument: \(error.message)")
} catch {
  print("Other error: \(error)")
}
```

--------------------------------

### Integrate MCP Tool with Swift AI SDK

Source: https://swift-ai-sdk-docs.vercel.app/providers/openai

Shows how to integrate the Model Context Protocol (MCP) tool for provider-executed operations. This example demonstrates setting up the MCP tool with server details and handling approvals for calls. MCP tool results are surfaced as tool calls/results with a JSON output payload.

```swift
import SwiftAISDK
import OpenAIProvider


let mcp = openai.tools.mcp(OpenAIMCPArgs(
  serverLabel: "zip1",
  serverUrl: "https://zip1.io/mcp",
  serverDescription: "Link shortener",
  requireApproval: .always
))


let result = try streamText(
  model: openai.responses("gpt-5"),
  prompt: "Shorten https://openai.com and return only the shortened URL.",
  tools: [
    "mcp": mcp
  ],
  toolChoice: .tool(toolName: "mcp"),
  experimentalApprove: { _ in
    // Approve (or deny) provider-executed MCP calls when OpenAI requests approval.
    .approve
  }
)


for try await delta in result.textStream { print(delta, terminator: "") }
print("")

```

--------------------------------

### Tool Calling with Alibaba Models

Source: https://swift-ai-sdk-docs.vercel.app/providers/alibaba

Demonstrates how to enable tool calling with Alibaba models, allowing for parallel execution of tools based on defined schemas.

```APIDOC
## POST /generateText (Tool Calling)

### Description
This endpoint enables tool calling functionality with Alibaba models, allowing the model to use predefined tools based on a provided schema for tasks like fetching weather information. It supports parallel execution of tools.

### Method
POST

### Endpoint
/generateText

### Parameters
#### Query Parameters
- **model** (string) - Required - The Alibaba model to use (e.g., "qwen-plus").
- **tools** (object) - Required - A dictionary mapping tool names to their definitions, including schema and execution logic.
- **prompt** (string) - Required - The user's prompt to the model.

### Request Body
(Not applicable for this example, parameters are passed directly)

### Request Example
```swift
import SwiftAISDK
import AlibabaProvider
import AISDKProvider
import AISDKProviderUtils


let weatherSchema = FlexibleSchema<JSONValue>(jsonSchema([
  "type": "object",
  "properties": [
    "location": ["type": "string"]
  ],
  "required": ["location"]
]))


let weather = tool(
  description: "Get the weather in a location",
  inputSchema: weatherSchema,
  execute: { input, _ in
    guard
      case let .object(obj) = input,
      case let .string(location)? = obj["location"]
    else {
      return .value(["error": "missing location"])
    }


    let temperature = 72 + Int.random(in: -10...10)
    return .value([
      "location": location,
      "temperature": temperature
    ])
  }
)


let result = try await generateText(
  model: alibaba("qwen-plus"),
  tools: ["weather": weather],
  prompt: "What is the weather in San Francisco?"
)
print(result.text)
```

### Response
#### Success Response (200)
- **text** (string) - The generated text response from the model, potentially including tool call results.

#### Response Example
```json
{
  "text": "The weather in San Francisco is 75 degrees."
}
```
```

--------------------------------

### Create Together.ai Language Model

Source: https://swift-ai-sdk-docs.vercel.app/providers/togetherai

This code illustrates how to create a Together.ai language model by providing a model ID to the 'togetherai' provider instance. The example uses 'google/gemma-2-9b-it' as the model identifier.

```swift
import TogetherAIProvider


let model = togetherai("google/gemma-2-9b-it")
```

--------------------------------

### Reference-to-Video Generation with Alibaba

Source: https://swift-ai-sdk-docs.vercel.app/providers/alibaba

Generates a video using reference images or videos for character consistency with Alibaba's video models via the Swift AI SDK. This example demonstrates setting reference URLs and other generation parameters.

```swift
import SwiftAISDK
import AlibabaProvider
import Foundation


let result = try await experimental_generateVideo(
  model: alibaba.video("wan2.6-r2v-flash"),
  prompt: "character1 walks through a beautiful garden and waves at the camera",
  resolution: "1280x720",
  duration: 5,
  providerOptions: [
    "alibaba": [
      "referenceUrls": ["https://example.com/character-reference.jpg"],
      "pollTimeoutMs": 600_000 // 10 minutes
    ]
  ]
)

try result.video.data.write(to: URL(fileURLWithPath: "video.mp4"))
```

--------------------------------

### Handling NoSpeechGeneratedError in Swift

Source: https://swift-ai-sdk-docs.vercel.app/ai-sdk-core/speech

Provides an example of how to handle the `NoSpeechGeneratedError` that is thrown when speech generation fails. The error object contains details about the cause and the responses received from the model.

```swift
import SwiftAISDK
import OpenAIProvider


do {
  _ = try await generateSpeech(
    model: openai.speech("tts-1"),
    text: "Hello, world!"
  )
} catch let error as NoSpeechGeneratedError {
  print("AI_NoSpeechGeneratedError")
  print("Cause:", error.cause ?? "none")
  print("Responses:", error.responses)
}
```

--------------------------------

### Apply Middleware to Registry in Swift AI SDK

Source: https://swift-ai-sdk-docs.vercel.app/ai-sdk-core/provider-management

Apply middleware to all language models accessed through the registry. This example enables reasoning extraction for all models in the registry.

```swift
import SwiftAISDK
import OpenAIProvider


let registry = createProviderRegistry(
  providers: [
    "openai": openai
  ],
  options: ProviderRegistryOptions(
    languageModelMiddleware: .single(
      extractReasoningMiddleware(
        options: ExtractReasoningOptions(tagName: "think")
      )
    )
  )
)


// All language models from this registry will have reasoning extraction enabled
let result = try await generateText(
  model: registry.languageModel(id: "openai:gpt-4o"),
  prompt: "Think step by step and wrap reasoning in <think> tags"
)
```

--------------------------------

### Create Customized Fal Provider Instance

Source: https://swift-ai-sdk-docs.vercel.app/providers/fal

Shows how to create a customized Fal provider instance using `createFal` with optional settings like API key, base URL, and custom headers. This allows for more control over the connection to the Fal AI service.

```swift
import FalProvider


let fal = createFal(settings: FalProviderSettings(
  apiKey: "your-api-key", // optional, defaults to FAL_API_KEY, falling back to FAL_KEY
  baseURL: "https://fal.run", // optional
  headers: ["X-Custom-Header": "value"] // optional
))
```

--------------------------------

### Instantiate Default Mistral Provider

Source: https://swift-ai-sdk-docs.vercel.app/providers/mistral

This code demonstrates how to import and use the default Mistral provider instance. It shows the basic setup for accessing the Mistral API with a specified model ID.

```swift
import MistralProvider


// Use the global mistral instance
let model = mistral("mistral-large-latest")
```

--------------------------------

### Image-to-Video Generation

Source: https://swift-ai-sdk-docs.vercel.app/ai-sdk-core/video-generation

Instructions on how to generate videos from an input image using the prompt object, supporting base64 strings and `Data`.

```APIDOC
## Image-to-Video Generation

Generate videos from an input image by providing it within the prompt object.

**Request Example (using image URL):**
```swift
let result = try await experimental_generateVideo(
  model: fal.video("hunyuan-video"),
  prompt: .imageToVideo(
    image: .string("https://example.com/my-image.png"),
    text: "Animate this image with gentle motion"
  )
)
```

**Request Example (using image data):**
```swift
let imageBytes: Data = /* ... */

let result = try await experimental_generateVideo(
  model: fal.video("hunyuan-video"),
  prompt: .imageToVideo(
    image: .data(imageBytes),
    text: "Animate this image"
  )
)
```
```
Tokens:
Raw