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/resp"
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 // Metadata for the response, check the presence of optional fields with the
54 // [resp.Field.IsPresent] method.
55 JSON struct {
56 Data resp.Field
57 Model resp.Field
58 Object resp.Field
59 Usage resp.Field
60 ExtraFields map[string]resp.Field
61 raw string
62 } `json:"-"`
63}
64
65// Returns the unmodified JSON received from the API
66func (r CreateEmbeddingResponse) RawJSON() string { return r.JSON.raw }
67func (r *CreateEmbeddingResponse) UnmarshalJSON(data []byte) error {
68 return apijson.UnmarshalRoot(data, r)
69}
70
71// The usage information for the request.
72type CreateEmbeddingResponseUsage struct {
73 // The number of tokens used by the prompt.
74 PromptTokens int64 `json:"prompt_tokens,required"`
75 // The total number of tokens used by the request.
76 TotalTokens int64 `json:"total_tokens,required"`
77 // Metadata for the response, check the presence of optional fields with the
78 // [resp.Field.IsPresent] method.
79 JSON struct {
80 PromptTokens resp.Field
81 TotalTokens resp.Field
82 ExtraFields map[string]resp.Field
83 raw string
84 } `json:"-"`
85}
86
87// Returns the unmodified JSON received from the API
88func (r CreateEmbeddingResponseUsage) RawJSON() string { return r.JSON.raw }
89func (r *CreateEmbeddingResponseUsage) UnmarshalJSON(data []byte) error {
90 return apijson.UnmarshalRoot(data, r)
91}
92
93// Represents an embedding vector returned by embedding endpoint.
94type Embedding struct {
95 // The embedding vector, which is a list of floats. The length of vector depends on
96 // the model as listed in the
97 // [embedding guide](https://platform.openai.com/docs/guides/embeddings).
98 Embedding []float64 `json:"embedding,required"`
99 // The index of the embedding in the list of embeddings.
100 Index int64 `json:"index,required"`
101 // The object type, which is always "embedding".
102 Object constant.Embedding `json:"object,required"`
103 // Metadata for the response, check the presence of optional fields with the
104 // [resp.Field.IsPresent] method.
105 JSON struct {
106 Embedding resp.Field
107 Index resp.Field
108 Object resp.Field
109 ExtraFields map[string]resp.Field
110 raw string
111 } `json:"-"`
112}
113
114// Returns the unmodified JSON received from the API
115func (r Embedding) RawJSON() string { return r.JSON.raw }
116func (r *Embedding) UnmarshalJSON(data []byte) error {
117 return apijson.UnmarshalRoot(data, r)
118}
119
120type EmbeddingModel = string
121
122const (
123 EmbeddingModelTextEmbeddingAda002 EmbeddingModel = "text-embedding-ada-002"
124 EmbeddingModelTextEmbedding3Small EmbeddingModel = "text-embedding-3-small"
125 EmbeddingModelTextEmbedding3Large EmbeddingModel = "text-embedding-3-large"
126)
127
128type EmbeddingNewParams struct {
129 // Input text to embed, encoded as a string or array of tokens. To embed multiple
130 // inputs in a single request, pass an array of strings or array of token arrays.
131 // The input must not exceed the max input tokens for the model (8192 tokens for
132 // `text-embedding-ada-002`), cannot be an empty string, and any array must be 2048
133 // dimensions or less.
134 // [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken)
135 // for counting tokens. Some models may also impose a limit on total number of
136 // tokens summed across inputs.
137 Input EmbeddingNewParamsInputUnion `json:"input,omitzero,required"`
138 // ID of the model to use. You can use the
139 // [List models](https://platform.openai.com/docs/api-reference/models/list) API to
140 // see all of your available models, or see our
141 // [Model overview](https://platform.openai.com/docs/models) for descriptions of
142 // them.
143 Model EmbeddingModel `json:"model,omitzero,required"`
144 // The number of dimensions the resulting output embeddings should have. Only
145 // supported in `text-embedding-3` and later models.
146 Dimensions param.Opt[int64] `json:"dimensions,omitzero"`
147 // A unique identifier representing your end-user, which can help OpenAI to monitor
148 // and detect abuse.
149 // [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).
150 User param.Opt[string] `json:"user,omitzero"`
151 // The format to return the embeddings in. Can be either `float` or
152 // [`base64`](https://pypi.org/project/pybase64/).
153 //
154 // Any of "float", "base64".
155 EncodingFormat EmbeddingNewParamsEncodingFormat `json:"encoding_format,omitzero"`
156 paramObj
157}
158
159// IsPresent returns true if the field's value is not omitted and not the JSON
160// "null". To check if this field is omitted, use [param.IsOmitted].
161func (f EmbeddingNewParams) IsPresent() bool { return !param.IsOmitted(f) && !f.IsNull() }
162
163func (r EmbeddingNewParams) MarshalJSON() (data []byte, err error) {
164 type shadow EmbeddingNewParams
165 return param.MarshalObject(r, (*shadow)(&r))
166}
167
168// Only one field can be non-zero.
169//
170// Use [param.IsOmitted] to confirm if a field is set.
171type EmbeddingNewParamsInputUnion struct {
172 OfString param.Opt[string] `json:",omitzero,inline"`
173 OfArrayOfStrings []string `json:",omitzero,inline"`
174 OfArrayOfTokens []int64 `json:",omitzero,inline"`
175 OfArrayOfTokenArrays [][]int64 `json:",omitzero,inline"`
176 paramUnion
177}
178
179// IsPresent returns true if the field's value is not omitted and not the JSON
180// "null". To check if this field is omitted, use [param.IsOmitted].
181func (u EmbeddingNewParamsInputUnion) IsPresent() bool { return !param.IsOmitted(u) && !u.IsNull() }
182func (u EmbeddingNewParamsInputUnion) MarshalJSON() ([]byte, error) {
183 return param.MarshalUnion[EmbeddingNewParamsInputUnion](u.OfString, u.OfArrayOfStrings, u.OfArrayOfTokens, u.OfArrayOfTokenArrays)
184}
185
186func (u *EmbeddingNewParamsInputUnion) asAny() any {
187 if !param.IsOmitted(u.OfString) {
188 return &u.OfString.Value
189 } else if !param.IsOmitted(u.OfArrayOfStrings) {
190 return &u.OfArrayOfStrings
191 } else if !param.IsOmitted(u.OfArrayOfTokens) {
192 return &u.OfArrayOfTokens
193 } else if !param.IsOmitted(u.OfArrayOfTokenArrays) {
194 return &u.OfArrayOfTokenArrays
195 }
196 return nil
197}
198
199// The format to return the embeddings in. Can be either `float` or
200// [`base64`](https://pypi.org/project/pybase64/).
201type EmbeddingNewParamsEncodingFormat string
202
203const (
204 EmbeddingNewParamsEncodingFormatFloat EmbeddingNewParamsEncodingFormat = "float"
205 EmbeddingNewParamsEncodingFormatBase64 EmbeddingNewParamsEncodingFormat = "base64"
206)