release: 2.0.0 (#466)

* feat(api): manual updates

* feat(client): support optional json html escaping

* feat(api): adds GPT-5 and new API features: platform.openai.com/docs/guides/gpt-5

* codegen metadata

* chore: document breaking changes

* chore: change readme warning and minimum version

* feat(client): rename union helpers

* chore: migrate examples

* release: 2.0.0

* release: 2.0.0

* Update CHANGELOG.md

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>
Co-authored-by: Jacob Zimmerman <[email protected]>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.12.0"
+  ".": "2.0.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 97
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-721e6ccaa72205ee14c71f8163129920464fb814b95d3df9567a9476bbd9b7fb.yml
-openapi_spec_hash: 2115413a21df8b5bf9e4552a74df4312
-config_hash: 9606bb315a193bfd8da0459040143242
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-d7e255da603b878e7e823135520211ce6a9e02890c9d549bbf3953a877ee5ef3.yml
+openapi_spec_hash: 3eb8d86c06f0bb5e1190983e5acfc9ba
+config_hash: 2e7cf948f94e24f94c7d12ba2de2734a

CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 2.0.0 (2025-08-07)
+
+Full Changelog: [v1.12.0...v2.0.0](https://github.com/openai/openai-go/compare/v1.12.0...v2.0.0)
+
+### Breaking changes
+
+With the launch of `custom` tools in Chat Completions, `function` tools have been renamed to clarify the difference between the two.
+
+`ChatCompletionToolParam` has become a union and is now named `ChatCompletionToolUnionParam`.
+
+Older versions of the SDK used function tools: to migrate 
+
+
+```diff
+- openai.ChatCompletionToolParam{
+-  Function: openai.FunctionDefinitionParam{
++ openai.ChatCompletionFunctionTool(
++  openai.FunctionDefinitionParam{
+    Name:        "get_weather",
+    Description: openai.String("Get weather at the given location"),
+    Parameters: openai.FunctionParameters{ … },
++  },
++ )
+- },
+```
+
+### Features
+
+* **api:** adds GPT-5 and new API features: platform.openai.com/docs/guides/gpt-5 ([af46c88](https://github.com/openai/openai-go/commit/af46c885ea2414ba2b960f5d3accce89699a6250))
+* **api:** manual updates ([219f209](https://github.com/openai/openai-go/commit/219f2092a6d7f1952d119b5b4ec32512956825ff))
+* **client:** remove HTML escaping in JSON ([aea5ebc](https://github.com/openai/openai-go/commit/aea5ebccacb4fd854197dbf2547821860a62debc))
+* **client:** rename union helpers ([645e881](https://github.com/openai/openai-go/commit/645e881dee5799d81fb4fd40d6494a296710d0ce))
+* **client:** support optional json html escaping ([1d2336b](https://github.com/openai/openai-go/commit/1d2336b0d92f810fad3bf5faf5bf9e74975adf61))
+
+
+### Bug Fixes
+
+* **client:** revert path param changes ([9239f06](https://github.com/openai/openai-go/commit/9239f06bf0cb537d80980cee140a90d07b6d14f2))
+
+
+### Chores
+
+* change readme warning and minimum version ([1d0e22f](https://github.com/openai/openai-go/commit/1d0e22f85593a70f006f285f4461a05243b0fd74))
+* document breaking changes ([afaa2b8](https://github.com/openai/openai-go/commit/afaa2b8482e8d10ea508716ad9b241517c9affa1))
+* migrate examples ([9c57dd7](https://github.com/openai/openai-go/commit/9c57dd72515aab1c6d05d604870c5d0cf7fc1652))
+
 ## 1.12.0 (2025-07-30)
 
 Full Changelog: [v1.11.1...v1.12.0](https://github.com/openai/openai-go/compare/v1.11.1...v1.12.0)

MIGRATION.md

@@ -1,6 +1,6 @@
 # OpenAI Go Migration Guide
 
-<a href="https://pkg.go.dev/github.com/openai/openai-go"><img src="https://pkg.go.dev/badge/github.com/openai/openai-go.svg" alt="Go Reference"></a>
+<a href="https://pkg.go.dev/github.com/openai/openai-go/v2"><img src="https://pkg.go.dev/badge/github.com/openai/openai-go.svg" alt="Go Reference"></a>
 
 This SDK includes breaking changes to improve the ergonomics of constructing parameters and accessing responses.
 

README.md

@@ -1,21 +1,21 @@
 # OpenAI Go API Library
 
-<a href="https://pkg.go.dev/github.com/openai/openai-go"><img src="https://pkg.go.dev/badge/github.com/openai/openai-go.svg" alt="Go Reference"></a>
+<a href="https://pkg.go.dev/github.com/openai/openai-go/v2"><img src="https://pkg.go.dev/badge/github.com/openai/openai-go.svg" alt="Go Reference"></a>
 
 The OpenAI Go library provides convenient access to the [OpenAI REST API](https://platform.openai.com/docs)
 from applications written in Go.
 
 > [!WARNING]
-> The latest version of this package uses a new design with significant breaking changes.
-> Please refer to the [migration guide](./MIGRATION.md) for more information on how to update your code.
+> The latest version of this package has small and limited breaking changes.
+> See the [changelog](CHANGELOG.md) for details.
 
 ## Installation
 
 <!-- x-release-please-start-version -->
 
 ```go
 import (
-	"github.com/openai/openai-go" // imported as openai
+	"github.com/openai/openai-go/v2" // imported as openai
 )
 ```
 
@@ -26,14 +26,14 @@ Or to pin the version:
 <!-- x-release-please-start-version -->
 
 ```sh
-go get -u 'github.com/openai/openai-go@v1.12.0'
+go get -u 'github.com/openai/openai-go@v2.0.0'
 ```
 
 <!-- x-release-please-end -->
 
 ## Requirements
 
-This library requires Go 1.18+.
+This library requires Go 1.21+.
 
 ## Usage
 
@@ -46,9 +46,9 @@ import (
 	"context"
 	"fmt"
 
-	"github.com/openai/openai-go"
-	"github.com/openai/openai-go/option"
-	"github.com/openai/openai-go/shared"
+	"github.com/openai/openai-go/v2"
+	"github.com/openai/openai-go/v2/option"
+	"github.com/openai/openai-go/v2/shared"
 )
 
 func main() {
@@ -589,7 +589,7 @@ client.Chat.Completions.New(
 				},
 			},
 		}},
-		Model: shared.ChatModelGPT4_1,
+		Model: shared.ChatModelGPT5,
 	},
 	// This sets the per-retry timeout
 	option.WithRequestTimeout(20*time.Second),
@@ -652,9 +652,9 @@ import (
 	"os"
 
 	"github.com/gin-gonic/gin"
-	"github.com/openai/openai-go"
-	"github.com/openai/openai-go/option"
-	"github.com/openai/openai-go/webhooks"
+	"github.com/openai/openai-go/v2"
+	"github.com/openai/openai-go/v2/option"
+	"github.com/openai/openai-go/v2/webhooks"
 )
 
 func main() {
@@ -663,7 +663,7 @@ func main() {
 	)
 
 	r := gin.Default()
-	
+
 	r.POST("/webhook", func(c *gin.Context) {
 		body, err := io.ReadAll(c.Request.Body)
 		if err != nil {
@@ -712,8 +712,8 @@ import (
 	"os"
 
 	"github.com/gin-gonic/gin"
-	"github.com/openai/openai-go"
-	"github.com/openai/openai-go/option"
+	"github.com/openai/openai-go/v2"
+	"github.com/openai/openai-go/v2/option"
 )
 
 func main() {
@@ -722,7 +722,7 @@ func main() {
 	)
 
 	r := gin.Default()
-	
+
 	r.POST("/webhook", func(c *gin.Context) {
 		body, err := io.ReadAll(c.Request.Body)
 		if err != nil {
@@ -737,7 +737,7 @@ func main() {
 			c.JSON(http.StatusBadRequest, gin.H{"error": "invalid signature"})
 			return
 		}
-		
+
 		c.JSON(http.StatusOK, gin.H{"message": "ok"})
 	})
 
@@ -770,7 +770,7 @@ client.Chat.Completions.New(
 				},
 			},
 		}},
-		Model: shared.ChatModelGPT4_1,
+		Model: shared.ChatModelGPT5,
 	},
 	option.WithMaxRetries(5),
 )
@@ -794,7 +794,7 @@ chatCompletion, err := client.Chat.Completions.New(
 				},
 			},
 		}},
-		Model: shared.ChatModelGPT4_1,
+		Model: shared.ChatModelGPT5,
 	},
 	option.WithResponseInto(&response),
 )
@@ -903,8 +903,8 @@ package main
 
 import (
 	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
-	"github.com/openai/openai-go"
-	"github.com/openai/openai-go/azure"
+	"github.com/openai/openai-go/v2"
+	"github.com/openai/openai-go/v2/azure"
 )
 
 func main() {

aliases.go

@@ -3,9 +3,9 @@
 package openai
 
 import (
-	"github.com/openai/openai-go/internal/apierror"
-	"github.com/openai/openai-go/packages/param"
-	"github.com/openai/openai-go/shared"
+	"github.com/openai/openai-go/v2/internal/apierror"
+	"github.com/openai/openai-go/v2/packages/param"
+	"github.com/openai/openai-go/v2/shared"
 )
 
 // aliased to make [param.APIUnion] private when embedding
@@ -19,6 +19,27 @@ type Error = apierror.Error
 // This is an alias to an internal type.
 type ChatModel = shared.ChatModel
 
+// Equals "gpt-5"
+const ChatModelGPT5 = shared.ChatModelGPT5
+
+// Equals "gpt-5-mini"
+const ChatModelGPT5Mini = shared.ChatModelGPT5Mini
+
+// Equals "gpt-5-nano"
+const ChatModelGPT5Nano = shared.ChatModelGPT5Nano
+
+// Equals "gpt-5-2025-08-07"
+const ChatModelGPT5_2025_08_07 = shared.ChatModelGPT5_2025_08_07
+
+// Equals "gpt-5-mini-2025-08-07"
+const ChatModelGPT5Mini2025_08_07 = shared.ChatModelGPT5Mini2025_08_07
+
+// Equals "gpt-5-nano-2025-08-07"
+const ChatModelGPT5Nano2025_08_07 = shared.ChatModelGPT5Nano2025_08_07
+
+// Equals "gpt-5-chat-latest"
+const ChatModelGPT5ChatLatest = shared.ChatModelGPT5ChatLatest
+
 // Equals "gpt-4.1"
 const ChatModelGPT4_1 = shared.ChatModelGPT4_1
 
@@ -259,6 +280,36 @@ const CompoundFilterTypeOr = shared.CompoundFilterTypeOr
 // This is an alias to an internal type.
 type CompoundFilterParam = shared.CompoundFilterParam
 
+// The input format for the custom tool. Default is unconstrained text.
+//
+// This is an alias to an internal type.
+type CustomToolInputFormatUnion = shared.CustomToolInputFormatUnion
+
+// Unconstrained free-form text.
+//
+// This is an alias to an internal type.
+type CustomToolInputFormatText = shared.CustomToolInputFormatText
+
+// A grammar defined by the user.
+//
+// This is an alias to an internal type.
+type CustomToolInputFormatGrammar = shared.CustomToolInputFormatGrammar
+
+// The input format for the custom tool. Default is unconstrained text.
+//
+// This is an alias to an internal type.
+type CustomToolInputFormatUnionParam = shared.CustomToolInputFormatUnionParam
+
+// Unconstrained free-form text.
+//
+// This is an alias to an internal type.
+type CustomToolInputFormatTextParam = shared.CustomToolInputFormatTextParam
+
+// A grammar defined by the user.
+//
+// This is an alias to an internal type.
+type CustomToolInputFormatGrammarParam = shared.CustomToolInputFormatGrammarParam
+
 // This is an alias to an internal type.
 type ErrorObject = shared.ErrorObject
 
@@ -339,16 +390,18 @@ const ReasoningSummaryDetailed = shared.ReasoningSummaryDetailed
 // This is an alias to an internal type.
 type ReasoningParam = shared.ReasoningParam
 
-// **o-series models only**
-//
 // Constrains effort on reasoning for
 // [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
-// supported values are `low`, `medium`, and `high`. Reducing reasoning effort can
-// result in faster responses and fewer tokens used on reasoning in a response.
+// supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
+// effort can result in faster responses and fewer tokens used on reasoning in a
+// response.
 //
 // This is an alias to an internal type.
 type ReasoningEffort = shared.ReasoningEffort
 
+// Equals "minimal"
+const ReasoningEffortMinimal = shared.ReasoningEffortMinimal
+
 // Equals "low"
 const ReasoningEffortLow = shared.ReasoningEffortLow