OpenAI Go API 库

OpenAI Go 库为使用 Go 语言编写的应用程序提供了便捷访问 OpenAI REST API 的能力。

[!WARNING] 此包的最新版本包含少量且有限的破坏性变更。 详情请参阅 变更日志。

安装

import (
	"github.com/openai/openai-go/v3" // 导入后别名为 openai
)

或指定固定版本：

go get -u 'github.com/openai/openai-go/v3@v3.30.0'

要求

本库要求 Go 1.22 或更高版本。

使用方法

本库完整的 API 文档请参见 api.md。

与 OpenAI 模型交互的主要接口是 Responses API。你可以使用以下代码从模型生成文本。

package main

import (
	"context"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	ctx := context.Background()
	client := openai.NewClient(
		option.WithAPIKey("My API Key"), // 默认从 os.LookupEnv("OPENAI_API_KEY") 获取
	)

	question := "写一首关于计算机的俳句"

	resp, err := client.Responses.New(ctx, responses.ResponseNewParams{
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(question)},
		Model: openai.ChatModelGPT5_2,
	})

	if err != nil {
		panic(err)
	}

	println(resp.OutputText())
}

response, err := client.Responses.New(ctx, responses.ResponseNewParams{
	Model: openai.ChatModelGPT5_2,
	Input: responses.ResponseNewParamsInputUnion{
		OfString: openai.String("法国的首都是哪里？"),
	},
})
if err != nil {
	panic(err)
}
fmt.Println("第一轮响应：", response.OutputText())

// 使用 PreviousResponseID 继续对话
response, err = client.Responses.New(ctx, responses.ResponseNewParams{
	Model:              openai.ChatModelGPT5_2,
	PreviousResponseID: openai.String(response.ID),
	Input: responses.ResponseNewParamsInputUnion{
		OfString: openai.String("那座城市的人口是多少？"),
	},
})
if err != nil {
	panic(err)
}
fmt.Println("第二轮响应：", response.OutputText())

conv, err := client.Conversations.New(ctx, conversations.ConversationNewParams{})
if err != nil {
	panic(err)
}
fmt.Println("已创建会话：", conv.ID)

response, err := client.Responses.New(ctx, responses.ResponseNewParams{
	Model: openai.ChatModelGPT5_2,
	Input: responses.ResponseNewParamsInputUnion{
		OfString: openai.String("你好！记住我最喜欢的颜色是蓝色。"),
	},
	Conversation: responses.ResponseNewParamsConversationUnion{
		OfConversationObject: &responses.ResponseConversationParam{
			ID: conv.ID,
		},
	},
})
if err != nil {
	panic(err)
}
fmt.Println("第一轮响应：", response.OutputText())

// 继续会话
response, err = client.Responses.New(ctx, responses.ResponseNewParams{
	Model: openai.ChatModelGPT5_2,
	Input: responses.ResponseNewParamsInputUnion{
		OfString: openai.String("我最喜欢的颜色是什么？"),
	},
	Conversation: responses.ResponseNewParamsConversationUnion{
		OfConversationObject: &responses.ResponseConversationParam{
			ID: conv.ID,
		},
	},
})
if err != nil {
	panic(err)
}
fmt.Println("第二轮响应：", response.OutputText())

items, err := client.Conversations.Items.List(ctx, conv.ID, conversations.ItemListParams{})
if err != nil {
	panic(err)
}
fmt.Println("会话包含", len(items.Data), "条记录")

ctx := context.Background()

stream := client.Responses.NewStreaming(ctx, responses.ResponseNewParams{
	Model: openai.ChatModelGPT5_2,
	Input: responses.ResponseNewParamsInputUnion{
		OfString: openai.String("写一首关于编程的俳句"),
	},
})

for stream.Next() {
	event := stream.Current()
	print(event.Delta)
}

if stream.Err() != nil {
	panic(stream.Err())
}

ctx := context.Background()

params := responses.ResponseNewParams{
	Model: openai.ChatModelGPT5_2,
	Input: responses.ResponseNewParamsInputUnion{
		OfString: openai.String("纽约市的天气如何？"),
	},
	Tools: []responses.ToolUnionParam{{
		OfFunction: &responses.FunctionToolParam{
			Name:        "get_weather",
			Description: openai.String("获取指定位置的天气"),
			Parameters: map[string]any{
				"type": "object",
				"properties": map[string]any{
					"location": map[string]string{
						"type": "string",
					},
				},
				"required": []string{"location"},
			},
		},
	}},
}

response, _ := client.Responses.New(ctx, params)

// 检查响应输出中的函数调用
for _, item := range response.Output {
	if item.Type == "function_call" {
		toolCall := item.AsFunctionCall()
		if toolCall.Name == "get_weather" {
			// 提取参数并调用你的函数
			var args map[string]any
			json.Unmarshal([]byte(toolCall.Arguments), &args)
			location := args["location"].(string)

			// 模拟获取天气数据
			weatherData := getWeather(location)
			fmt.Printf("地点 %s 的天气：%s\n", location, weatherData)

			// 使用函数结果继续对话
			response, _ = client.Responses.New(ctx, responses.ResponseNewParams{
				Model:              openai.ChatModelGPT5_2,
				PreviousResponseID: openai.String(response.ID),
				Input: responses.ResponseNewParamsInputUnion{
					OfInputItemList: []responses.ResponseInputItemUnionParam{{
						OfFunctionCallOutput: &responses.ResponseInputItemFunctionCallOutputParam{
							CallID: toolCall.CallID,
							Output: responses.ResponseInputItemFunctionCallOutputOutputUnionParam{
								OfString: openai.String(weatherData),
							},
						},
					}},
				},
			})
		}
	}
}

import (
	"encoding/json"
	"github.com/invopop/jsonschema"
	// ...
)

```go
// 一个将被转换为结构化输出（Structured Outputs）响应模式的结构体
type HistoricalComputer struct {
	Origin       Origin   `json:"origin" jsonschema_description:"计算机的起源"`
	Name         string   `json:"full_name" jsonschema_description:"设备型号的名称"`
	Legacy       string   `json:"legacy" jsonschema:"enum=positive,enum=neutral,enum=negative" jsonschema_description:"其对计算领域的影响"`
	NotableFacts []string `json:"notable_facts" jsonschema_description:"关于该计算机的一些关键事实"`
}

type Origin struct {
	YearBuilt    int64  `json:"year_of_construction" jsonschema_description:"制造年份"`
	Organization string `json:"organization" jsonschema_description:"负责其开发的组织"`
}

// 结构化输出使用 JSON 模式的一个子集
// 这些标志是符合该子集所必需的
func GenerateSchema[T any]() map[string]any {
	reflector := jsonschema.Reflector{
		AllowAdditionalProperties: false,
		DoNotReference:            true,
	}
	var v T
	schema := reflector.Reflect(v)

	data, _ := json.Marshal(schema)
	var result map[string]any
	json.Unmarshal(data, &result)
	return result
}

// 在初始化时生成 JSON 模式
var HistoricalComputerSchema = GenerateSchema[HistoricalComputer]()

func main() {
	client := openai.NewClient()
	ctx := context.Background()

	response, err := client.Responses.New(ctx, responses.ResponseNewParams{
		Model: openai.ChatModelGPT5_2,
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("什么计算机运行了第一个神经网络？"),
		},
		Text: responses.ResponseTextConfigParam{
			Format: responses.ResponseFormatTextConfigParamOfJSONSchema(
				"historical_computer",
				HistoricalComputerSchema,
			),
		},
	})
	if err != nil {
		panic(err)
	}

	// 提取到一个类型安全的结构体中
	var historicalComputer HistoricalComputer
	_ = json.Unmarshal([]byte(response.OutputText()), &historicalComputer)

	historicalComputer.Name
	historicalComputer.Origin.YearBuilt
	historicalComputer.Origin.Organization
	for i, fact := range historicalComputer.NotableFacts {
		// ...
	}
}

聊天补全 API

此前的标准（将无限期支持）文本生成接口是 聊天补全 API。你可以使用以下代码通过该 API 从模型生成文本。

package main

import (
	"context"

	"github.com/openai/openai-go/v3"
)

func main() {
	client := openai.NewClient()

	chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.DeveloperMessage("你是一个说话像海盗的编程助手。"),
			openai.UserMessage("我如何在 Go 中检查切片是否为空？"),
		},
		Model: openai.ChatModelGPT5_2,
	})
	if err != nil {
		panic(err)
	}

	println(chatCompletion.Choices[0].Message.Content)
}

请求字段

openai 库对请求字段使用 Go 1.24+ encoding/json 发布版中的 omitzero 语义。

必需的基本类型字段（int64、string 等）带有标签 `json:"...,required"`。这些字段即使为零值也会始终序列化。

可选的基本类型被包装在 param.Opt[T] 中。这些字段可通过提供的构造函数设置，如 openai.String(string)、openai.Int(int64) 等。

任何 param.Opt[T]、map、slice、struct 或字符串枚举均使用标签 `json:"...,omitzero"`。其零值被视为省略。

param.IsOmitted(any) 函数可用于确认任意 omitzero 字段是否存在。

p := openai.ExampleParams{
	ID:   "id_xxx",             // 必需属性
	Name: openai.String("..."), // 可选属性

	Point: openai.Point{
		X: 0,             // 必需字段，序列化为 0
		Y: openai.Int(1), // 可选字段，序列化为 1
		// ... 省略的非必需字段不会被序列化
	},

	Origin: openai.Origin{}, // [Origin] 的零值被视为省略
}

若要发送 null 而非 param.Opt[T]，请使用 param.Null[T]()。 若要发送 null 而非结构体 T，请使用 param.NullStruct[T]()。

p.Name = param.Null[string]()       // 发送 'null' 而非字符串
p.Point = param.NullStruct[Point]() // 发送 'null' 而非结构体

param.IsNull(p.Name)  // true
param.IsNull(p.Point) // true

请求结构体包含 .SetExtraFields(map[string]any) 方法，可用于在请求体中发送不符合规范的字段。额外字段会覆盖具有相同键的结构体字段。出于安全考虑，请仅对可信数据使用 SetExtraFields。

若要发送自定义值而非结构体，请使用 param.Override[T](value)。

// 当 API 指定某种类型，但你想发送其他内容时，使用 [SetExtraFields]：
p.SetExtraFields(map[string]any{
	"x": 0.01, // 将 "x" 作为浮点数发送，而非整数
})

// 发送数字而非对象
custom := param.Override[openai.FooParams](12)

请求联合类型（Unions）

联合类型表示为一个结构体，其每个变体字段前缀为 "Of"， 仅允许一个字段非零。非零字段将被序列化。

联合类型的子属性可通过联合结构体上的方法访问。 这些方法返回指向底层数据的可变指针（如果存在）。

// 仅允许一个字段非零，使用 param.IsOmitted() 检查字段是否已设置
type AnimalUnionParam struct {
	OfCat *Cat `json:",omitzero,inline`
	OfDog *Dog `json:",omitzero,inline`
}

animal := AnimalUnionParam{
	OfCat: &Cat{
		Name: "Whiskers",
		Owner: PersonParam{
			Address: AddressParam{Street: "3333 Coyote Hill Rd", Zip: 0},
		},
	},
}

// 修改字段
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

响应对象（Response objects）

响应结构体中的所有字段均为普通值类型（非指针或包装器）。
响应结构体还包含一个特殊的 JSON 字段，用于存储每个属性的元数据。

type Animal struct {
	Name   string `json:"name,nullable"`
	Owners int    `json:"owners"`
	Age    int    `json:"age"`
	JSON   struct {
		Name        respjson.Field
		Owner       respjson.Field
		Age         respjson.Field
		ExtraFields map[string]respjson.Field
	} `json:"-"`
}

要处理可选数据，请使用 JSON 字段上的 .Valid() 方法。
.Valid() 在字段不为 null、不存在或无法被序列化时返回 true。

若 .Valid() 为 false，则对应字段将为其零值。

raw := `{"owners": 1, "name": null}`

var res Animal
json.Unmarshal([]byte(raw), &res)

// 访问常规字段

res.Owners // 1
res.Name   // ""
res.Age    // 0

// 可选字段检查

res.JSON.Owners.Valid() // true
res.JSON.Name.Valid()   // false
res.JSON.Age.Valid()    // false

// 原始 JSON 值

res.JSON.Owners.Raw()                  // "1"
res.JSON.Name.Raw() == "null"          // true
res.JSON.Name.Raw() == respjson.Null   // true
res.JSON.Age.Raw() == ""               // true
res.JSON.Age.Raw() == respjson.Omitted // true

这些 .JSON 结构体还包含一个 ExtraFields 映射，其中包含 JSON 响应中未在结构体中定义的任何属性。
这对于 SDK 尚未支持的 API 功能非常有用。

body := res.JSON.ExtraFields["my_unexpected_field"].Raw()

响应联合类型（Response Unions）

在响应中，联合类型（union）由一个扁平化的结构体表示，该结构体包含每个对象变体的所有可能字段。
要将其转换为具体变体，请使用 .AsFooVariant() 方法；如果存在，也可使用 .AsAny() 方法。

如果响应值联合类型包含基本类型（primitive values），则基本类型字段将与属性并列，但会以 Of 为前缀，并带有标签 json:"...,inline"。

type AnimalUnion struct {
	// 来自变体 [Dog], [Cat]
	Owner Person `json:"owner"`
	// 来自变体 [Dog]
	DogBreed string `json:"dog_breed"`
	// 来自变体 [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

	JSON struct {
		Owner respjson.Field
		// ...
	} `json:"-"`
}

// 如果是 animal 变体
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// 根据变体进行切换
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

请求选项（RequestOptions）

本库使用函数式选项模式（functional options pattern）。
option 包中定义的函数返回一个 RequestOption，它是一个修改 RequestConfig 的闭包。
这些选项可以提供给客户端，也可以在单个请求中指定。例如：

client := openai.NewClient(
	// 为客户端发起的每个请求添加一个头部
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Responses.New(context.TODO(), responses.ResponseNewParams{...},
	// 覆盖头部
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// 使用 sjson 语法向请求体添加未文档化的字段
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

调试时，请求选项 option.WithDebugLog(nil) 可能会有帮助。

请参阅完整的请求选项列表。

分页（Pagination）

本库为处理分页列表端点提供了一些便利功能。

你可以使用 .ListAutoPaging() 方法遍历所有页面中的项目：

iter := client.FineTuning.Jobs.ListAutoPaging(context.TODO(), openai.FineTuningJobListParams{
	Limit: openai.Int(20),
})
// 根据需要自动获取更多页面。
for iter.Next() {
	fineTuningJob := iter.Current()
	fmt.Printf("%+v\n", fineTuningJob)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

或者，你也可以使用简单的 .List() 方法获取单个页面，并接收一个标准响应对象，该对象包含如 .GetNextPage() 等辅助方法，例如：

page, err := client.FineTuning.Jobs.List(context.TODO(), openai.FineTuningJobListParams{
	Limit: openai.Int(20),
})
for page != nil {
	for _, job := range page.Data {
		fmt.Printf("%+v\n", job)
	}
	page, err = page.GetNextPage()
}
if err != nil {
	panic(err.Error())
}

错误（Errors）

当 API 返回非成功状态码时，我们会返回一个类型为 *openai.Error 的错误。
该错误包含请求的 StatusCode、*http.Request 和 *http.Response 值，以及错误体的 JSON 数据（类似于 SDK 中的其他响应对象）。

我们建议你使用 errors.As 模式来处理错误：

_, err := client.FineTuning.Jobs.New(context.TODO(), openai.FineTuningJobNewParams{
	Model:        openai.FineTuningJobNewParamsModel("gpt-4o"),
	TrainingFile: "file-abc123",
})
if err != nil {
	var apierr *openai.Error
	if errors.As(err, &apierr) {
		println(string(apierr.DumpRequest(true)))  // 打印序列化的 HTTP 请求
		println(string(apierr.DumpResponse(true))) // 打印序列化的 HTTP 响应
	}
	panic(err.Error()) // GET "/fine_tuning/jobs": 400 Bad Request { ... }
}

当发生其他错误时，它们将以未包装形式返回；例如，
如果 HTTP 传输失败，你可能会收到一个包装了 *net.OpError 的 *url.Error。

超时（Timeouts）

默认情况下，请求不会超时；请使用 context 配置请求生命周期的超时时间。

注意：如果请求被重试，context 超时不会重新计时。
要设置每次重试的超时时间，请使用 option.WithRequestTimeout()。

// 此处设置的是整个请求（包括所有重试）的超时时间。
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
client.Responses.New(
	ctx,
	responses.ResponseNewParams{
		Model: openai.ChatModelGPT5_2,
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("How can I list all files in a directory using Python?"),
		},
	},
	// 此处设置的是每次重试的超时时间
	option.WithRequestTimeout(20*time.Second),
)

文件上传

在 multipart 请求中，对应文件上传的请求参数类型为 io.Reader。默认情况下，io.Reader 的内容将以文件名为 "anonymous_file"、内容类型（content-type）为 "application/octet-stream" 的 multipart 表单部分发送。

可以通过在 io.Reader 的运行时类型上实现 Name() string 或 ContentType() string 方法来自定义文件名和内容类型。注意：os.File 已实现 Name() string，因此通过 os.Open 返回的文件将使用磁盘上的实际文件名发送。

我们还提供了一个辅助函数 openai.File(reader io.Reader, filename string, contentType string)，可用于为任意 io.Reader 包装指定的文件名和内容类型。

// 来自文件系统的文件
file, err := os.Open("input.jsonl")
openai.FileNewParams{
	File:    file,
	Purpose: openai.FilePurposeFineTune,
}

// 来自字符串的文件
openai.FileNewParams{
	File:    strings.NewReader("my file contents"),
	Purpose: openai.FilePurposeFineTune,
}

// 自定义文件名和 contentType
openai.FileNewParams{
	File:    openai.File(strings.NewReader(`{"hello": "foo"}`), "file.go", "application/json"),
	Purpose: openai.FilePurposeFineTune,
}

Webhook 验证

验证 webhook 签名是_可选但推荐的_。

有关 webhook 的更多信息，请参阅 API 文档。

解析 webhook 负载

在大多数使用场景中，你可能希望同时验证 webhook 并解析其负载。为此，我们提供了方法 client.Webhooks.Unwrap()，该方法会解析 webhook 请求并验证其确实由 OpenAI 发送。如果签名无效，此方法将返回错误。

请注意，body 参数应为服务器发送的原始 JSON 字节（不要先解析它）。Unwrap() 方法将在确认 webhook 来自 OpenAI 后，为你将此 JSON 解析为事件对象。

package main

import (
	"io"
	"log"
	"net/http"
	"os"

	"github.com/gin-gonic/gin"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/webhooks"
)

func main() {
	client := openai.NewClient(
		option.WithWebhookSecret(os.Getenv("OPENAI_WEBHOOK_SECRET")), // 默认使用环境变量；此处显式指定。
	)

	r := gin.Default()

	r.POST("/webhook", func(c *gin.Context) {
		body, err := io.ReadAll(c.Request.Body)
		if err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "读取请求体失败"})
			return
		}
		defer c.Request.Body.Close()

		webhookEvent, err := client.Webhooks.Unwrap(body, c.Request.Header)
		if err != nil {
			log.Printf("无效的 webhook 签名: %v", err)
			c.JSON(http.StatusBadRequest, gin.H{"error": "签名无效"})
			return
		}

		switch event := webhookEvent.AsAny().(type) {
		case webhooks.ResponseCompletedWebhookEvent:
			log.Printf("响应完成: %+v", event.Data)
		case webhooks.ResponseFailedWebhookEvent:
			log.Printf("响应失败: %+v", event.Data)
		default:
			log.Printf("未处理的事件类型: %T", event)
		}

		c.JSON(http.StatusOK, gin.H{"message": "ok"})
	})

	r.Run(":8000")
}

直接验证 webhook 负载

在某些情况下，你可能希望在解析负载之前单独验证 webhook。如果你倾向于分别处理这两个步骤，我们提供了 client.Webhooks.VerifySignature() 方法，仅用于验证 webhook 请求的签名。与 Unwrap() 类似，如果签名无效，此方法将返回错误。

请注意，body 参数应为服务器发送的原始 JSON 字节（不要先解析它）。你需要在验证签名后再自行解析 body。

package main

import (
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"

	"github.com/gin-gonic/gin"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	client := openai.NewClient(
		option.WithWebhookSecret(os.Getenv("OPENAI_WEBHOOK_SECRET")), // 默认使用环境变量；此处显式指定。
	)

	r := gin.Default()

	r.POST("/webhook", func(c *gin.Context) {
		body, err := io.ReadAll(c.Request.Body)
		if err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": "读取请求体失败"})
			return
		}
		defer c.Request.Body.Close()

		err = client.Webhooks.VerifySignature(body, c.Request.Header)
		if err != nil {
			log.Printf("无效的 webhook 签名: %v", err)
			c.JSON(http.StatusBadRequest, gin.H{"error": "签名无效"})
			return
		}

		c.JSON(http.StatusOK, gin.H{"message": "ok"})
	})

	r.Run(":8000")
}

重试机制

默认情况下，某些错误会自动重试 2 次，并采用短指数退避策略。 默认重试所有连接错误、408 请求超时、409 冲突、429 速率限制以及 >=500 的内部错误。

你可以使用 WithMaxRetries 选项来配置或禁用此行为：

// 为所有请求配置默认值：
client := openai.NewClient(
	option.WithMaxRetries(0), // 默认值为 2
)

// 为单个请求覆盖设置：
client.Responses.New(
	context.TODO(),
	responses.ResponseNewParams{
		Model: openai.ChatModelGPT5_2,
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("如何在 JavaScript 中获取当前星期几的名称？"),
		},
	},
	option.WithMaxRetries(5),
)

访问原始响应数据（如响应头）

你可以使用 option.WithResponseInto() 请求选项访问原始 HTTP 响应数据。当你需要检查响应头、状态码或其他详细信息时，这非常有用。

// 创建一个变量用于存储 HTTP 响应
var httpResp *http.Response
response, err := client.Responses.New(
	context.TODO(),
	responses.ResponseNewParams{
		Model: openai.ChatModelGPT5_2,
		Input: responses.ResponseNewParamsInputUnion{
			OfString: openai.String("说这是一次测试"),
		},
	},
	option.WithResponseInto(&httpResp),
)
if err != nil {
	// 处理错误
}
fmt.Printf("%+v\n", response)

fmt.Printf("状态码: %d\n", httpResp.StatusCode)
fmt.Printf("响应头: %+#v\n", httpResp.Header)

发起自定义/未文档化的请求

本库为方便访问已文档化的 API 而进行了类型标注。若您需要访问未文档化的端点（endpoints）、参数（params）或响应属性（response properties），仍可使用本库。

未文档化的端点

要向未文档化的端点发起请求，您可以使用 client.Get、client.Post 及其他 HTTP 动词方法。客户端上的 RequestOptions（如重试机制）在发起此类请求时仍将生效。

var (
    // params 可以是 io.Reader、[]byte、可被 encoding/json 序列化的对象，
    // 或本库中定义的“…Params”结构体。
    params map[string]any

    // result 可以是 []byte、*http.Response、可被 encoding/json 反序列化的对象，
    // 或本库中定义的模型。
    result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
    …
}

未文档化的请求参数

若需使用未文档化的参数发起请求，您可以使用 option.WithQuerySet() 或 option.WithJSONSet() 方法。

params := FooNewParams{
    ID:   "id_xxxx",
    Data: FooNewParamsData{
        FirstName: openai.String("John"),
    },
}
client.Foo.New(context.Background(), params, option.WithJSONSet("data.last_name", "Doe"))

未文档化的响应属性

要访问未文档化的响应属性，您可以通过 result.JSON.RawJSON() 获取响应的原始 JSON 字符串，或通过 result.JSON.Foo.Raw() 获取结果中特定字段的原始 JSON。

任何未在响应结构体中声明的字段都会被保存，并可通过 result.JSON.ExtraFields() 访问，该方法返回一个 map[string]Field 类型的额外字段集合。

中间件（Middleware）

我们提供 option.WithMiddleware，用于将指定的中间件应用于请求。

func Logger(req *http.Request, next option.MiddlewareNext) (res *http.Response, err error) {
	// 请求前处理
	start := time.Now()
	LogReq(req)

	// 将请求转发给下一个处理器
	res, err = next(req)

	// 请求后处理
	end := time.Now()
	LogRes(res, err, start - end)

    return res, err
}

client := openai.NewClient(
	option.WithMiddleware(Logger),
)

当以变长参数形式提供多个中间件时，中间件将从左到右依次应用。如果多次调用 option.WithMiddleware（例如先在客户端设置，再在方法中设置），则客户端设置的中间件会先执行，方法中设置的中间件随后执行。

您也可以使用 option.WithHTTPClient(client) 替换默认的 http.Client。仅接受一个 HTTP 客户端（这会覆盖之前设置的客户端），且该客户端将在所有中间件处理完毕后接收请求。

Microsoft Azure OpenAI

要在 Azure OpenAI 上使用本库，请使用 azure 包中的 option.RequestOption 函数。

package main

import (
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/azure"
)

func main() {
	const azureOpenAIEndpoint = "https://<azure-openai-resource>.openai.azure.com"

	// 最新的 API 版本（包括预览版）可在此处找到：
	// https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#rest-api-versionng
	const azureOpenAIAPIVersion = "2024-06-01"

	tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)

	if err != nil {
		fmt.Printf("Failed to create the DefaultAzureCredential: %s", err)
		os.Exit(1)
	}

	client := openai.NewClient(
		azure.WithEndpoint(azureOpenAIEndpoint, azureOpenAIAPIVersion),

		// 选择使用 TokenCredential 或 API Key 进行身份验证
		azure.WithTokenCredential(tokenCredential),
		// 或 azure.WithAPIKey(azureOpenAIAPIKey),
	)
}

语义化版本控制（Semantic versioning）

本包通常遵循 SemVer 规范，但某些不兼容的变更可能会作为次要版本发布：

1. 对库内部实现的更改，这些部分虽技术上公开，但并非为外部使用而设计或文档化。（若您依赖此类内部实现，请提交 GitHub Issue 告知我们。）
2. 我们认为在实践中不会影响绝大多数用户的变更。

我们高度重视向后兼容性，并努力确保您能获得顺畅的升级体验。

我们非常期待您的反馈；请通过 Issue 提交问题、错误或建议。

贡献指南

详见 贡献文档。

openai-go 快速上手指南

环境准备

• Go 版本要求：1.22 或更高版本
• 前置依赖：无特殊依赖，标准库 + 本包即可
• API 密钥：需在 OpenAI 平台 获取 API Key，或设置环境变量 OPENAI_API_KEY

🇨🇳 国内开发者建议使用代理或镜像服务加速访问 OpenAI API（如通过 Cloudflare Workers、Vercel 或自建中转）

安装步骤

在项目中导入：

import (
	"github.com/openai/openai-go/v3" // 默认别名为 openai
)

或通过命令行安装指定版本：

go get -u 'github.com/openai/openai-go/v3@v3.30.0'

基本使用

以下是最简单的文本生成示例：

package main

import (
	"context"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/option"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	ctx := context.Background()
	client := openai.NewClient(
		option.WithAPIKey("My API Key"), // 可省略，默认读取环境变量 OPENAI_API_KEY
	)

	question := "写一首关于计算机的俳句"

	resp, err := client.Responses.New(ctx, responses.ResponseNewParams{
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(question)},
		Model: openai.ChatModelGPT5_2,
	})

	if err != nil {
		panic(err)
	}

	println(resp.OutputText())
}

运行后将输出模型生成的回答文本。