1// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2
3package openai
4
5import (
6 "context"
7 "errors"
8 "fmt"
9 "net/http"
10
11 "github.com/openai/openai-go/internal/apijson"
12 "github.com/openai/openai-go/internal/requestconfig"
13 "github.com/openai/openai-go/option"
14 "github.com/openai/openai-go/packages/param"
15 "github.com/openai/openai-go/packages/resp"
16 "github.com/openai/openai-go/shared/constant"
17)
18
19// UploadService contains methods and other services that help with interacting
20// with the openai API.
21//
22// Note, unlike clients, this service does not read variables from the environment
23// automatically. You should not instantiate this service directly, and instead use
24// the [NewUploadService] method instead.
25type UploadService struct {
26 Options []option.RequestOption
27 Parts UploadPartService
28}
29
30// NewUploadService generates a new service that applies the given options to each
31// request. These options are applied after the parent client's options (if there
32// is one), and before any request-specific options.
33func NewUploadService(opts ...option.RequestOption) (r UploadService) {
34 r = UploadService{}
35 r.Options = opts
36 r.Parts = NewUploadPartService(opts...)
37 return
38}
39
40// Creates an intermediate
41// [Upload](https://platform.openai.com/docs/api-reference/uploads/object) object
42// that you can add
43// [Parts](https://platform.openai.com/docs/api-reference/uploads/part-object) to.
44// Currently, an Upload can accept at most 8 GB in total and expires after an hour
45// after you create it.
46//
47// Once you complete the Upload, we will create a
48// [File](https://platform.openai.com/docs/api-reference/files/object) object that
49// contains all the parts you uploaded. This File is usable in the rest of our
50// platform as a regular File object.
51//
52// For certain `purpose` values, the correct `mime_type` must be specified. Please
53// refer to documentation for the
54// [supported MIME types for your use case](https://platform.openai.com/docs/assistants/tools/file-search#supported-files).
55//
56// For guidance on the proper filename extensions for each purpose, please follow
57// the documentation on
58// [creating a File](https://platform.openai.com/docs/api-reference/files/create).
59func (r *UploadService) New(ctx context.Context, body UploadNewParams, opts ...option.RequestOption) (res *Upload, err error) {
60 opts = append(r.Options[:], opts...)
61 path := "uploads"
62 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
63 return
64}
65
66// Cancels the Upload. No Parts may be added after an Upload is cancelled.
67func (r *UploadService) Cancel(ctx context.Context, uploadID string, opts ...option.RequestOption) (res *Upload, err error) {
68 opts = append(r.Options[:], opts...)
69 if uploadID == "" {
70 err = errors.New("missing required upload_id parameter")
71 return
72 }
73 path := fmt.Sprintf("uploads/%s/cancel", uploadID)
74 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, nil, &res, opts...)
75 return
76}
77
78// Completes the
79// [Upload](https://platform.openai.com/docs/api-reference/uploads/object).
80//
81// Within the returned Upload object, there is a nested
82// [File](https://platform.openai.com/docs/api-reference/files/object) object that
83// is ready to use in the rest of the platform.
84//
85// You can specify the order of the Parts by passing in an ordered list of the Part
86// IDs.
87//
88// The number of bytes uploaded upon completion must match the number of bytes
89// initially specified when creating the Upload object. No Parts may be added after
90// an Upload is completed.
91func (r *UploadService) Complete(ctx context.Context, uploadID string, body UploadCompleteParams, opts ...option.RequestOption) (res *Upload, err error) {
92 opts = append(r.Options[:], opts...)
93 if uploadID == "" {
94 err = errors.New("missing required upload_id parameter")
95 return
96 }
97 path := fmt.Sprintf("uploads/%s/complete", uploadID)
98 err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, body, &res, opts...)
99 return
100}
101
102// The Upload object can accept byte chunks in the form of Parts.
103type Upload struct {
104 // The Upload unique identifier, which can be referenced in API endpoints.
105 ID string `json:"id,required"`
106 // The intended number of bytes to be uploaded.
107 Bytes int64 `json:"bytes,required"`
108 // The Unix timestamp (in seconds) for when the Upload was created.
109 CreatedAt int64 `json:"created_at,required"`
110 // The Unix timestamp (in seconds) for when the Upload will expire.
111 ExpiresAt int64 `json:"expires_at,required"`
112 // The name of the file to be uploaded.
113 Filename string `json:"filename,required"`
114 // The object type, which is always "upload".
115 Object constant.Upload `json:"object,required"`
116 // The intended purpose of the file.
117 // [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose)
118 // for acceptable values.
119 Purpose string `json:"purpose,required"`
120 // The status of the Upload.
121 //
122 // Any of "pending", "completed", "cancelled", "expired".
123 Status UploadStatus `json:"status,required"`
124 // The `File` object represents a document that has been uploaded to OpenAI.
125 File FileObject `json:"file,nullable"`
126 // Metadata for the response, check the presence of optional fields with the
127 // [resp.Field.IsPresent] method.
128 JSON struct {
129 ID resp.Field
130 Bytes resp.Field
131 CreatedAt resp.Field
132 ExpiresAt resp.Field
133 Filename resp.Field
134 Object resp.Field
135 Purpose resp.Field
136 Status resp.Field
137 File resp.Field
138 ExtraFields map[string]resp.Field
139 raw string
140 } `json:"-"`
141}
142
143// Returns the unmodified JSON received from the API
144func (r Upload) RawJSON() string { return r.JSON.raw }
145func (r *Upload) UnmarshalJSON(data []byte) error {
146 return apijson.UnmarshalRoot(data, r)
147}
148
149// The status of the Upload.
150type UploadStatus string
151
152const (
153 UploadStatusPending UploadStatus = "pending"
154 UploadStatusCompleted UploadStatus = "completed"
155 UploadStatusCancelled UploadStatus = "cancelled"
156 UploadStatusExpired UploadStatus = "expired"
157)
158
159type UploadNewParams struct {
160 // The number of bytes in the file you are uploading.
161 Bytes int64 `json:"bytes,required"`
162 // The name of the file to upload.
163 Filename string `json:"filename,required"`
164 // The MIME type of the file.
165 //
166 // This must fall within the supported MIME types for your file purpose. See the
167 // supported MIME types for assistants and vision.
168 MimeType string `json:"mime_type,required"`
169 // The intended purpose of the uploaded file.
170 //
171 // See the
172 // [documentation on File purposes](https://platform.openai.com/docs/api-reference/files/create#files-create-purpose).
173 //
174 // Any of "assistants", "batch", "fine-tune", "vision", "user_data", "evals".
175 Purpose FilePurpose `json:"purpose,omitzero,required"`
176 paramObj
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 (f UploadNewParams) IsPresent() bool { return !param.IsOmitted(f) && !f.IsNull() }
182
183func (r UploadNewParams) MarshalJSON() (data []byte, err error) {
184 type shadow UploadNewParams
185 return param.MarshalObject(r, (*shadow)(&r))
186}
187
188type UploadCompleteParams struct {
189 // The ordered list of Part IDs.
190 PartIDs []string `json:"part_ids,omitzero,required"`
191 // The optional md5 checksum for the file contents to verify if the bytes uploaded
192 // matches what you expect.
193 Md5 param.Opt[string] `json:"md5,omitzero"`
194 paramObj
195}
196
197// IsPresent returns true if the field's value is not omitted and not the JSON
198// "null". To check if this field is omitted, use [param.IsOmitted].
199func (f UploadCompleteParams) IsPresent() bool { return !param.IsOmitted(f) && !f.IsNull() }
200
201func (r UploadCompleteParams) MarshalJSON() (data []byte, err error) {
202 type shadow UploadCompleteParams
203 return param.MarshalObject(r, (*shadow)(&r))
204}