Documentation

Installation

Swift Package Manager

dependencies:[.package(url:"https://github.com/MacPaw/OpenAI.git", branch:"main")]

Usage

Initialization

letopenAI=OpenAI(apiToken:"YOUR_TOKEN_HERE")

letconfiguration=OpenAI.Configuration(token:"YOUR_TOKEN_HERE", organizationIdentifier:"YOUR_ORGANIZATION_ID_HERE", timeoutInterval:60.0)letopenAI=OpenAI(configuration: configuration)

Using the SDK for other providers except OpenAI

Cancelling requests

lettask=Task{do{letchatResult=tryawait openAIClient.chats(query:.init(messages:[], model:"asd"))}catch{        // Handle cancellation or error}}            task.cancel()

Text and prompting

Responses

publicprotocolOpenAIProtocol{    // ...varresponses:ResponsesEndpointProtocol{get}    // ...}

letclient:OpenAIProtocol= /* client initialization code */let query=CreateModelResponseQuery(    input:.textInput("Write a one-sentence bedtime story about a unicorn."),    model:.gpt4_1)letresponse:ResponseObject=tryawait client.responses.createResponse(query: query)// ...

// ...foroutputin response.output{switch output{case.outputMessage(let outputMessage):forcontentin outputMessage.content{switch content{case.OutputTextContent(let textContent):print(textContent.text)case.RefusalContent(let refusalContent):print(refusalContent.refusal)}}default:        // Unhandled output items. Handle or throw an error.}}

Chat Completions

letquery=ChatQuery(    messages:[.user(.init(content:.string("Who are you?")))],    model:.gpt4_o)letresult=tryawait openAI.chats(query: query)print(result.choices.first?.message.content??"")// printed to console:// I'm an AI language model created by OpenAI, designed to assist with a wide range of questions and tasks. How can I help you today?

Function calling

Images

Create Image

structImagesQuery:Codable{    /// A text description of the desired image(s). The maximum length is 1000 characters.publicletprompt:String    /// The number of images to generate. Must be between 1 and 10.publicletn:Int?    /// The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.publicletsize:String?}

structImagesResult:Codable,Equatable{publicstructURLResult:Codable,Equatable{publicleturl:String}publicletcreated:TimeIntervalpublicletdata:[URLResult]}

letquery=ImagesQuery(prompt:"White cat with heterochromia sitting on the kitchen table", n:1, size:"1024x1024")openAI.images(query: query){ resultin  //Handle result here}//orletresult=tryawait openAI.images(query: query)

(lldb) po result▿ ImagesResult  - created : 1671453505.0  ▿ data : 1 element    ▿ 0 : URLResult      - url : "https://oaidalleapiprodscus.blob.core.windows.net/private/org-CWjU5cDIzgCcVjq10pp5yX5Q/user-GoBXgChvLBqLHdBiMJBUbPqF/img-WZVUK2dOD4HKbKwW1NeMJHBd.png?st=2022-12-19T11%3A38%3A25Z&se=2022-12-19T13%3A38%3A25Z&sp=r&sv=2021-08-06&sr=b&rscd=inline&rsct=image/png&skoid=6aaadede-4fb3-4698-a8f6-684d7786b067&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skt=2022-12-19T09%3A35%3A16Z&ske=2022-12-20T09%3A35%3A16Z&sks=b&skv=2021-08-06&sig=mh52rmtbQ8CXArv5bMaU6lhgZHFBZz/ePr4y%2BJwLKOc%3D"

Create Image Edit

publicstructImageEditsQuery:Codable{    /// The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.publicletimage:DatapublicletfileName:String    /// An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where image should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as image.publicletmask:Data?publicletmaskFileName:String?    /// A text description of the desired image(s). The maximum length is 1000 characters.publicletprompt:String    /// The number of images to generate. Must be between 1 and 10.publicletn:Int?    /// The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.publicletsize:String?}

letdata= image.pngData()letquery=ImageEditQuery(image: data, fileName:"whitecat.png", prompt:"White cat with heterochromia sitting on the kitchen table with a bowl of food", n:1, size:"1024x1024")openAI.imageEdits(query: query){ resultin  //Handle result here}//orletresult=tryawait openAI.imageEdits(query: query)

Create Image Variation

publicstructImageVariationsQuery:Codable{    /// The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.publicletimage:DatapublicletfileName:String    /// The number of images to generate. Must be between 1 and 10.publicletn:Int?    /// The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.publicletsize:String?}

letdata= image.pngData()letquery=ImageVariationQuery(image: data, fileName:"whitecat.png", n:1, size:"1024x1024")openAI.imageVariations(query: query){ resultin  //Handle result here}//orletresult=tryawait openAI.imageVariations(query: query)

Audio

Audio Create Speech

publicstructAudioSpeechQuery:Codable,Equatable{    //...publicletmodel:Model // tts-1 or tts-1-hdpublicletinput:Stringpublicletvoice:AudioSpeechVoicepublicletresponseFormat:AudioSpeechResponseFormatpublicletspeed:String? // Initializes with Double?    //...}

/// Audio data for one of the following formats :`mp3`, `opus`, `aac`, `flac`, `pcm`publicletaudioData:Data?

letquery=AudioSpeechQuery(model:.tts_1, input:"Hello, world!", voice:.alloy, responseFormat:.mp3, speed:1.0)openAI.audioCreateSpeech(query: query){ resultin    // Handle response here}//orletresult=tryawait openAI.audioCreateSpeech(query: query)

Audio Create Speech Streaming

openAI.audioCreateSpeechStream(query: query){ partialResultinswitch partialResult{case.success(let result):print(result.audio)case.failure(let error):        //Handle chunk error here}} completion:{ errorin    //Handle streaming error here}

openAI.audioCreateSpeechStream(query: query).sink{ completionin        //Handle completion result here} receiveValue:{ resultin        //Handle chunk here}.store(in:&cancellables)

fortryawaitresultin openAI.audioCreateSpeechStream(query: query){   //Handle result here}

Audio Transcriptions

publicstructAudioTranscriptionQuery:Codable,Equatable{publicletfile:DatapublicletfileName:Stringpublicletmodel:Modelpublicletprompt:String?publiclettemperature:Double?publicletlanguage:String?}

publicstructAudioTranscriptionResult:Codable,Equatable{publiclettext:String}

letdata=Data(contentsOfURL:...)letquery=AudioTranscriptionQuery(file: data, fileName:"audio.m4a", model:.whisper_1)        openAI.audioTranscriptions(query: query){ resultin    //Handle result here}//orletresult=tryawait openAI.audioTranscriptions(query: query)

Audio Translations

publicstructAudioTranslationQuery:Codable,Equatable{publicletfile:DatapublicletfileName:Stringpublicletmodel:Modelpublicletprompt:String?publiclettemperature:Double?}

publicstructAudioTranslationResult:Codable,Equatable{publiclettext:String}

letdata=Data(contentsOfURL:...)letquery=AudioTranslationQuery(file: data, fileName:"audio.m4a", model:.whisper_1)  openAI.audioTranslations(query: query){ resultin    //Handle result here}//orletresult=tryawait openAI.audioTranslations(query: query)

Structured Outputs

Tools

Remote MCP (Model Context Protocol)

MCP Tool Integration

// Create an MCP tool for connecting to a remote serverletmcpTool=Tool.mcpTool(.init(        _type:.mcp,        serverLabel:"GitHub_MCP_Server",        serverUrl:"https://api.githubcopilot.com/mcp/",        headers:.init(additionalProperties:["Authorization":"Bearer YOUR_TOKEN_HERE"]),        allowedTools:.case1(["search_repositories","get_file_contents"]),        requireApproval:.case2(.always)))letquery=ChatQuery(    messages:[.user(.init(content:.string("Search for Swift repositories on GitHub")))],    model:.gpt4_o,    tools:[mcpTool])

import MCPimport OpenAI// Connect to MCP server using the MCP Swift libraryletmcpClient=MCP.Client(name:"MyApp", version:"1.0.0")lettransport=HTTPClientTransport(    endpoint:URL(string:"https://api.githubcopilot.com/mcp/")!,    configuration:URLSessionConfiguration.default)letresult=tryawait mcpClient.connect(transport: transport)lettoolsResponse=tryawait mcpClient.listTools()// Create OpenAI MCP tool with discovered toolsletenabledToolNames= toolsResponse.tools.map{ $0.name}letmcpTool=Tool.mcpTool(.init(        _type:.mcp,        serverLabel:"GitHub_MCP_Server",        serverUrl:"https://api.githubcopilot.com/mcp/",        headers:.init(additionalProperties: authHeaders),        allowedTools:.case1(enabledToolNames),        requireApproval:.case2(.always)))// Use in chat completionletquery=ChatQuery(    messages:[.user(.init(content:.string("Help me search GitHub repositories")))],    model:.gpt4_o,    tools:[mcpTool])letchatResult=tryawait openAI.chats(query: query)

// Handle MCP tool calls in streaming responsesfortryawaitresultin openAI.chatsStream(query: query){forchoicein result.choices{iflet outputItem= choice.delta.content{switch outputItem{case.mcpToolCall(let mcpCall):print("MCP tool call:\(mcpCall.name)")iflet output= mcpCall.output{print("Result:\(output)")}case.mcpApprovalRequest(let approvalRequest):                // Handle approval request if requireApproval is enabledprint("MCP tool requires approval:\(approvalRequest)")default:                // Handle other output typesbreak}}}}

Specialized models

Embeddings

structEmbeddingsQuery:Codable{    /// ID of the model to use.publicletmodel:Model    /// Input text to get embeddings forpublicletinput:String}

structEmbeddingsResult:Codable,Equatable{publicstructEmbedding:Codable,Equatable{publicletobject:Stringpublicletembedding:[Double]publicletindex:Int}publicletdata:[Embedding]publicletusage:Usage}

letquery=EmbeddingsQuery(model:.textSearchBabbageDoc, input:"The food was delicious and the waiter...")openAI.embeddings(query: query){ resultin  //Handle response here}//orletresult=tryawait openAI.embeddings(query: query)

(lldb) po result▿ EmbeddingsResult  ▿ data : 1 element    ▿ 0 : Embedding      - object : "embedding"      ▿ embedding : 2048 elements        - 0 : 0.0010535449        - 1 : 0.024234328        - 2 : -0.0084999        - 3 : 0.008647452    .......        - 2044 : 0.017536353        - 2045 : -0.005897616        - 2046 : -0.026559394        - 2047 : -0.016633155      - index : 0(lldb)

Moderations

publicstructModerationsQuery:Codable{publicletinput:Stringpublicletmodel:Model?}

publicstructModerationsResult:Codable,Equatable{publicletid:Stringpublicletmodel:Modelpublicletresults:[CategoryResult]}

letquery=ModerationsQuery(input:"I want to kill them.")openAI.moderations(query: query){ resultin  //Handle result here}//orletresult=tryawait openAI.moderations(query: query)

Other APIs

Models

publicextensionModel{staticletgpt4_1="gpt-4.1"staticletgpt4_1_mini="gpt-4.1-mini"staticletgpt4_1_nano="gpt-4.1-nano"staticletgpt4_turbo_preview="gpt-4-turbo-preview"staticletgpt4_vision_preview="gpt-4-vision-preview"staticletgpt4_0125_preview="gpt-4-0125-preview"staticletgpt4_1106_preview="gpt-4-1106-preview"staticletgpt4="gpt-4"staticletgpt4_0613="gpt-4-0613"staticletgpt4_0314="gpt-4-0314"staticletgpt4_32k="gpt-4-32k"staticletgpt4_32k_0613="gpt-4-32k-0613"staticletgpt4_32k_0314="gpt-4-32k-0314"staticletgpt3_5Turbo="gpt-3.5-turbo"staticletgpt3_5Turbo_0125="gpt-3.5-turbo-0125"staticletgpt3_5Turbo_1106="gpt-3.5-turbo-1106"staticletgpt3_5Turbo_0613="gpt-3.5-turbo-0613"staticletgpt3_5Turbo_0301="gpt-3.5-turbo-0301"staticletgpt3_5Turbo_16k="gpt-3.5-turbo-16k"staticletgpt3_5Turbo_16k_0613="gpt-3.5-turbo-16k-0613"staticlettextDavinci_003="text-davinci-003"staticlettextDavinci_002="text-davinci-002"staticlettextCurie="text-curie-001"staticlettextBabbage="text-babbage-001"staticlettextAda="text-ada-001"staticlettextDavinci_001="text-davinci-001"staticletcodeDavinciEdit_001="code-davinci-edit-001"staticlettts_1="tts-1"staticlettts_1_hd="tts-1-hd"staticletwhisper_1="whisper-1"staticletdall_e_2="dall-e-2"staticletdall_e_3="dall-e-3"staticletdavinci="davinci"staticletcurie="curie"staticletbabbage="babbage"staticletada="ada"staticlettextEmbeddingAda="text-embedding-ada-002"staticlettextSearchAda="text-search-ada-doc-001"staticlettextSearchBabbageDoc="text-search-babbage-doc-001"staticlettextSearchBabbageQuery001="text-search-babbage-query-001"staticlettextEmbedding3="text-embedding-3-small"staticlettextEmbedding3Large="text-embedding-3-large"staticlettextModerationStable="text-moderation-stable"staticlettextModerationLatest="text-moderation-latest"staticletmoderation="text-moderation-007"}

letquery=ChatQuery(model:.gpt4_turbo_preview, messages:[.init(role:.system, content:"You are Librarian-GPT. You know everything about the books."),.init(role:.user, content:"Who wrote Harry Potter?")])letresult=tryawait openAI.chats(query: query)XCTAssertFalse(result.choices.isEmpty)

List Models

publicstructModelsResult:Codable,Equatable{publicletdata:[ModelResult]publicletobject:String}

openAI.models(){ resultin  //Handle result here}//orletresult=tryawait openAI.models()

Retrieve Model

publicstructModelQuery:Codable,Equatable{publicletmodel:Model}

publicstructModelResult:Codable,Equatable{publicletid:Modelpublicletobject:StringpublicletownedBy:String}

letquery=ModelQuery(model:.gpt4)openAI.model(query: query){ resultin  //Handle result here}//orletresult=tryawait openAI.model(query: query)

Utilities

publicstructVector{    /// Returns the similarity between two vectors    ///    /// - Parameters:    ///     - a: The first vector    ///     - b: The second vectorpublicstaticfunc cosineSimilarity(a:[Double], b:[Double])->Double{returndot(a, b)/(mag(a)* mag(b))}    /// Returns the difference between two vectors. Cosine distance is defined as `1 - cosineSimilarity(a, b)`    ///    /// - Parameters:    ///     - a: The first vector    ///     - b: The second vectorpublicfunc cosineDifference(a:[Double], b:[Double])->Double{return1- Self.cosineSimilarity(a: a, b: b)}}

letvector1=[0.213123,0.3214124,0.421412,0.3214521251,0.412412,0.3214124,0.1414124,0.3214521251,0.213123,0.3214124,0.1414124,0.4214214,0.213123,0.3214124,0.1414124,0.3214521251,0.213123,0.3214124,0.1414124,0.3214521251]letvector2=[0.213123,0.3214124,0.1414124,0.3214521251,0.213123,0.3214124,0.1414124,0.3214521251,0.213123,0.511515,0.1414124,0.3214521251,0.213123,0.3214124,0.1414124,0.3214521251,0.213123,0.3214124,0.1414124,0.3213213]letsimilarity=Vector.cosineSimilarity(a: vector1, b: vector2)print(similarity) //0.9510201910206734

Assistants

Create Assistant

letquery=AssistantsQuery(model:Model.gpt4_o_mini, name: name, description: description, instructions: instructions, tools: tools, toolResources: toolResources)openAI.assistantCreate(query: query){ resultin   //Handle response here}

Modify Assistant

letquery=AssistantsQuery(model:Model.gpt4_o_mini, name: name, description: description, instructions: instructions, tools: tools, toolResources: toolResources)openAI.assistantModify(query: query, assistantId:"asst_1234"){ resultin    //Handle response here}

List Assistants

openAI.assistants(){ resultin   //Handle response here}

Threads

Create Thread

letthreadsQuery=ThreadsQuery(messages:[Chat(role: message.role, content: message.content)])openAI.threads(query: threadsQuery){ resultin  //Handle response here}

Create and Run Thread

letthreadsQuery=ThreadQuery(messages:[Chat(role: message.role, content: message.content)])letthreadRunQuery=ThreadRunQuery(assistantId:"asst_1234"  thread: threadsQuery)openAI.threadRun(query: threadRunQuery){ resultin  //Handle response here}

Get Threads Messages

openAI.threadsMessages(threadId: currentThreadId){ resultin  //Handle response here}

Add Message to Thread

letquery=MessageQuery(role: message.role.rawValue, content: message.content)openAI.threadsAddMessage(threadId: currentThreadId, query: query){ resultin  //Handle response here}

Runs

Create Run

letrunsQuery=RunsQuery(assistantId:  currentAssistantId)openAI.runs(threadId: threadsResult.id, query: runsQuery){ resultin  //Handle response here}

Retrieve Run

openAI.runRetrieve(threadId: currentThreadId, runId: currentRunId){ resultin  //Handle response here}

Retrieve Run Steps

openAI.runRetrieveSteps(threadId: currentThreadId, runId: currentRunId){ resultin  //Handle response here}

Submit Tool Outputs for Run

letoutput=RunToolOutputsQuery.ToolOutput(toolCallId:"call123", output:"Success")letquery=RunToolOutputsQuery(toolOutputs:[output])openAI.runSubmitToolOutputs(threadId: currentThreadId, runId: currentRunId, query: query){ resultin  //Handle response here}

Files

Upload file

letquery=FilesQuery(purpose:"assistants", file: fileData, fileName: url.lastPathComponent, contentType:"application/pdf")openAI.files(query: query){ resultin  //Handle response here}

Support for other providers

Option 1: Use.relaxed parsing option

Option 2: Specify parsing options separately

Handle missing keys in responses

letconfiguration=OpenAI.Configuration(token:"", parsingOptions:.fillRequiredFieldIfKeyNotFound)

Handle missing values in responses

What if a provider returns additional fields?

Example Project

Contribution Guidelines

UseConventional Commits principles in naming PRs and branches:

Write description to pull requests in following format:

Links

License

MIT LicenseCopyright (c) 2023 MacPaw Inc.Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.