1// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
3package openai
4
5import (
6 "context"
7 "net/http"
8
9 "github.com/openai/openai-go/internal/apijson"
10 "github.com/openai/openai-go/internal/requestconfig"
11 "github.com/openai/openai-go/option"
12 "github.com/openai/openai-go/packages/param"
13 "github.com/openai/openai-go/packages/respjson"
14 "github.com/openai/openai-go/shared/constant"
15)
16
17// EmbeddingService contains methods and other services that help with interacting
18// with the openai API.
19//
20// Note, unlike clients, this service does not read variables from the environment
21// automatically. You should not instantiate this service directly, and instead use
22// the [NewEmbeddingService] method instead.
23type EmbeddingService struct {
24 Options []option.RequestOption
25}
26
27// NewEmbeddingService generates a new service that applies the given options to
28// each request. These options are applied after the parent client's options (if
29// there is one), and before any request-specific options.
30func NewEmbeddingService(opts ...option.RequestOption) (r EmbeddingService) {
31 r = EmbeddingService{}
32 r.Options = opts
33 return
34}
35
36// Creates an embedding vector representing the input text.
37func (r *EmbeddingService) New(ctx context.Context, body EmbeddingNewParams, opts ...option.RequestOption) (res *CreateEmbeddingResponse, err error) {
38 opts = append(r.Options[:], opts...)
39 path := "embeddings"
40 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
41 return
42}
43
44type CreateEmbeddingResponse struct {
45 // The list of embeddings generated by the model.
46 Data []Embedding `json:"data,required"`
47 // The name of the model used to generate the embedding.
48 Model string `json:"model,required"`
49 // The object type, which is always "list".
50 Object constant.List `json:"object,required"`
51 // The usage information for the request.
52 Usage CreateEmbeddingResponseUsage `json:"usage,required"`
53 // JSON contains metadata for fields, check presence with [respjson.Field.Valid].
54 JSON struct {
55 Data respjson.Field
56 Model respjson.Field
57 Object respjson.Field
58 Usage respjson.Field
59 ExtraFields map[string]respjson.Field
60 raw string
61 } `json:"-"`
62}
63
64// Returns the unmodified JSON received from the API
65func (r CreateEmbeddingResponse) RawJSON() string { return r.JSON.raw }
66func (r *CreateEmbeddingResponse) UnmarshalJSON(data []byte) error {
67 return apijson.UnmarshalRoot(data, r)
68}
69
70// The usage information for the request.
71type CreateEmbeddingResponseUsage struct {
72 // The number of tokens used by the prompt.
73 PromptTokens int64 `json:"prompt_tokens,required"`
74 // The total number of tokens used by the request.
75 TotalTokens int64 `json:"total_tokens,required"`
76 // JSON contains metadata for fields, check presence with [respjson.Field.Valid].
77 JSON struct {
78 PromptTokens respjson.Field
79 TotalTokens respjson.Field
80 ExtraFields map[string]respjson.Field
81 raw string
82 } `json:"-"`
83}
84
85// Returns the unmodified JSON received from the API
86func (r CreateEmbeddingResponseUsage) RawJSON() string { return r.JSON.raw }
87func (r *CreateEmbeddingResponseUsage) UnmarshalJSON(data []byte) error {
88 return apijson.UnmarshalRoot(data, r)
89}
90
91// Represents an embedding vector returned by embedding endpoint.
92type Embedding struct {
93 // The embedding vector, which is a list of floats. The length of vector depends on
94 // the model as listed in the
95 // [embedding guide](https://platform.openai.com/docs/guides/embeddings).
96 Embedding []float64 `json:"embedding,required"`
97 // The index of the embedding in the list of embeddings.
98 Index int64 `json:"index,required"`
99 // The object type, which is always "embedding".
100 Object constant.Embedding `json:"object,required"`
101 // JSON contains metadata for fields, check presence with [respjson.Field.Valid].
102 JSON struct {
103 Embedding respjson.Field
104 Index respjson.Field
105 Object respjson.Field
106 ExtraFields map[string]respjson.Field
107 raw string
108 } `json:"-"`
109}
110
111// Returns the unmodified JSON received from the API
112func (r Embedding) RawJSON() string { return r.JSON.raw }
113func (r *Embedding) UnmarshalJSON(data []byte) error {
114 return apijson.UnmarshalRoot(data, r)
115}
116
117type EmbeddingModel = string
118
119const (
120 EmbeddingModelTextEmbeddingAda002 EmbeddingModel = "text-embedding-ada-002"
121 EmbeddingModelTextEmbedding3Small EmbeddingModel = "text-embedding-3-small"
122 EmbeddingModelTextEmbedding3Large EmbeddingModel = "text-embedding-3-large"
123)
124
125type EmbeddingNewParams struct {
126 // Input text to embed, encoded as a string or array of tokens. To embed multiple
127 // inputs in a single request, pass an array of strings or array of token arrays.
128 // The input must not exceed the max input tokens for the model (8192 tokens for
129 // all embedding models), cannot be an empty string, and any array must be 2048
130 // dimensions or less.
131 // [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken)
132 // for counting tokens. In addition to the per-input token limit, all embedding
133 // models enforce a maximum of 300,000 tokens summed across all inputs in a single
134 // request.
135 Input EmbeddingNewParamsInputUnion `json:"input,omitzero,required"`
136 // ID of the model to use. You can use the
137 // [List models](https://platform.openai.com/docs/api-reference/models/list) API to
138 // see all of your available models, or see our
139 // [Model overview](https://platform.openai.com/docs/models) for descriptions of
140 // them.
141 Model EmbeddingModel `json:"model,omitzero,required"`
142 // The number of dimensions the resulting output embeddings should have. Only
143 // supported in `text-embedding-3` and later models.
144 Dimensions param.Opt[int64] `json:"dimensions,omitzero"`
145 // A unique identifier representing your end-user, which can help OpenAI to monitor
146 // and detect abuse.
147 // [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
148 User param.Opt[string] `json:"user,omitzero"`
149 // The format to return the embeddings in. Can be either `float` or
150 // [`base64`](https://pypi.org/project/pybase64/).
151 //
152 // Any of "float", "base64".
153 EncodingFormat EmbeddingNewParamsEncodingFormat `json:"encoding_format,omitzero"`
154 paramObj
155}
156
157func (r EmbeddingNewParams) MarshalJSON() (data []byte, err error) {
158 type shadow EmbeddingNewParams
159 return param.MarshalObject(r, (*shadow)(&r))
160}
161func (r *EmbeddingNewParams) UnmarshalJSON(data []byte) error {
162 return apijson.UnmarshalRoot(data, r)
163}
164
165// Only one field can be non-zero.
166//
167// Use [param.IsOmitted] to confirm if a field is set.
168type EmbeddingNewParamsInputUnion struct {
169 OfString param.Opt[string] `json:",omitzero,inline"`
170 OfArrayOfStrings []string `json:",omitzero,inline"`
171 OfArrayOfTokens []int64 `json:",omitzero,inline"`
172 OfArrayOfTokenArrays [][]int64 `json:",omitzero,inline"`
173 paramUnion
174}
175
176func (u EmbeddingNewParamsInputUnion) MarshalJSON() ([]byte, error) {
177 return param.MarshalUnion(u, u.OfString, u.OfArrayOfStrings, u.OfArrayOfTokens, u.OfArrayOfTokenArrays)
178}
179func (u *EmbeddingNewParamsInputUnion) UnmarshalJSON(data []byte) error {
180 return apijson.UnmarshalRoot(data, u)
181}
182
183func (u *EmbeddingNewParamsInputUnion) asAny() any {
184 if !param.IsOmitted(u.OfString) {
185 return &u.OfString.Value
186 } else if !param.IsOmitted(u.OfArrayOfStrings) {
187 return &u.OfArrayOfStrings
188 } else if !param.IsOmitted(u.OfArrayOfTokens) {
189 return &u.OfArrayOfTokens
190 } else if !param.IsOmitted(u.OfArrayOfTokenArrays) {
191 return &u.OfArrayOfTokenArrays
192 }
193 return nil
194}
195
196// The format to return the embeddings in. Can be either `float` or
197// [`base64`](https://pypi.org/project/pybase64/).
198type EmbeddingNewParamsEncodingFormat string
199
200const (
201 EmbeddingNewParamsEncodingFormatFloat EmbeddingNewParamsEncodingFormat = "float"
202 EmbeddingNewParamsEncodingFormatBase64 EmbeddingNewParamsEncodingFormat = "base64"
203)