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/respjson"
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 // JSON contains metadata for fields, check presence with [respjson.Field.Valid].
127 JSON struct {
128 ID respjson.Field
129 Bytes respjson.Field
130 CreatedAt respjson.Field
131 ExpiresAt respjson.Field
132 Filename respjson.Field
133 Object respjson.Field
134 Purpose respjson.Field
135 Status respjson.Field
136 File respjson.Field
137 ExtraFields map[string]respjson.Field
138 raw string
139 } `json:"-"`
140}
141
142// Returns the unmodified JSON received from the API
143func (r Upload) RawJSON() string { return r.JSON.raw }
144func (r *Upload) UnmarshalJSON(data []byte) error {
145 return apijson.UnmarshalRoot(data, r)
146}
147
148// The status of the Upload.
149type UploadStatus string
150
151const (
152 UploadStatusPending UploadStatus = "pending"
153 UploadStatusCompleted UploadStatus = "completed"
154 UploadStatusCancelled UploadStatus = "cancelled"
155 UploadStatusExpired UploadStatus = "expired"
156)
157
158type UploadNewParams struct {
159 // The number of bytes in the file you are uploading.
160 Bytes int64 `json:"bytes,required"`
161 // The name of the file to upload.
162 Filename string `json:"filename,required"`
163 // The MIME type of the file.
164 //
165 // This must fall within the supported MIME types for your file purpose. See the
166 // supported MIME types for assistants and vision.
167 MimeType string `json:"mime_type,required"`
168 // The intended purpose of the uploaded file.
169 //
170 // See the
171 // [documentation on File purposes](https://platform.openai.com/docs/api-reference/files/create#files-create-purpose).
172 //
173 // Any of "assistants", "batch", "fine-tune", "vision", "user_data", "evals".
174 Purpose FilePurpose `json:"purpose,omitzero,required"`
175 paramObj
176}
177
178func (r UploadNewParams) MarshalJSON() (data []byte, err error) {
179 type shadow UploadNewParams
180 return param.MarshalObject(r, (*shadow)(&r))
181}
182func (r *UploadNewParams) UnmarshalJSON(data []byte) error {
183 return apijson.UnmarshalRoot(data, r)
184}
185
186type UploadCompleteParams struct {
187 // The ordered list of Part IDs.
188 PartIDs []string `json:"part_ids,omitzero,required"`
189 // The optional md5 checksum for the file contents to verify if the bytes uploaded
190 // matches what you expect.
191 Md5 param.Opt[string] `json:"md5,omitzero"`
192 paramObj
193}
194
195func (r UploadCompleteParams) MarshalJSON() (data []byte, err error) {
196 type shadow UploadCompleteParams
197 return param.MarshalObject(r, (*shadow)(&r))
198}
199func (r *UploadCompleteParams) UnmarshalJSON(data []byte) error {
200 return apijson.UnmarshalRoot(data, r)
201}