Uploads

Create upload

uploads.create(UploadCreateParams**kwargs) -> Upload

post /uploads

Creates an intermediate Upload object that you can add Parts to. Currently, an Upload can accept at most 8 GB in total and expires after an hour after you create it.

Once you complete the Upload, we will create a File object that contains all the parts you uploaded. This File is usable in the rest of our platform as a regular File object.

For certain purpose values, the correct mime_type must be specified. Please refer to documentation for the supported MIME types for your use case.

For guidance on the proper filename extensions for each purpose, please follow the documentation on creating a File.

Returns the Upload object with status pending.

Parameters

bytes: int

The number of bytes in the file you are uploading.
filename: str

The name of the file to upload.
mime_type: str

The MIME type of the file.

This must fall within the supported MIME types for your file purpose. See the supported MIME types for assistants and vision.
purpose: FilePurpose

The intended purpose of the uploaded file.

See the documentation on File purposes.
- "assistants"
- "batch"
- "fine-tune"
- "vision"
- "user_data"
- "evals"
expires_after: Optional[ExpiresAfter]

The expiration policy for a file. By default, files with purpose=batch expire after 30 days and all other files are persisted until they are manually deleted.
- anchor: Literal["created_at"]
  
  Anchor timestamp after which the expiration policy applies. Supported anchors: created_at.
  - "created_at"
- seconds: int
  
  The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

Returns

class Upload: …

The Upload object can accept byte chunks in the form of Parts.
- id: str
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: int
  
  The intended number of bytes to be uploaded.
- created_at: int
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: int
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: str
  
  The name of the file to be uploaded.
- object: Literal["upload"]
  
  The object type, which is always "upload".
  - "upload"
- purpose: str
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: Literal["pending", "completed", "cancelled", "expired"]
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: Optional[FileObject]
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: str
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: int
    
    The size of the file, in bytes.
  - created_at: int
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: str
    
    The name of the file.
  - object: Literal["file"]
    
    The object type, which is always file.
    - "file"
  - purpose: Literal["assistants", "assistants_output", "batch", 5 more]
    
    The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
    - "assistants"
    - "assistants_output"
    - "batch"
    - "batch_output"
    - "fine-tune"
    - "fine-tune-results"
    - "vision"
    - "user_data"
  - status: Literal["uploaded", "processed", "error"]
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: Optional[int]
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: Optional[str]
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
upload = client.uploads.create(
    bytes=0,
    filename="filename",
    mime_type="mime_type",
    purpose="assistants",
)
print(upload.id)

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "expires_at": 0,
  "filename": "filename",
  "object": "upload",
  "purpose": "purpose",
  "status": "pending",
  "file": {
    "id": "id",
    "bytes": 0,
    "created_at": 0,
    "filename": "filename",
    "object": "file",
    "purpose": "assistants",
    "status": "uploaded",
    "expires_at": 0,
    "status_details": "status_details"
  }
}

Complete upload

uploads.complete(strupload_id, UploadCompleteParams**kwargs) -> Upload

post /uploads/{upload_id}/complete

Completes the Upload.

Within the returned Upload object, there is a nested File object that is ready to use in the rest of the platform.

You can specify the order of the Parts by passing in an ordered list of the Part IDs.

The number of bytes uploaded upon completion must match the number of bytes initially specified when creating the Upload object. No Parts may be added after an Upload is completed. Returns the Upload object with status completed, including an additional file property containing the created usable File object.

Parameters

upload_id: str
part_ids: Sequence[str]

The ordered list of Part IDs.
md5: Optional[str]

The optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.

Returns

class Upload: …

The Upload object can accept byte chunks in the form of Parts.
- id: str
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: int
  
  The intended number of bytes to be uploaded.
- created_at: int
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: int
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: str
  
  The name of the file to be uploaded.
- object: Literal["upload"]
  
  The object type, which is always "upload".
  - "upload"
- purpose: str
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: Literal["pending", "completed", "cancelled", "expired"]
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: Optional[FileObject]
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: str
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: int
    
    The size of the file, in bytes.
  - created_at: int
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: str
    
    The name of the file.
  - object: Literal["file"]
    
    The object type, which is always file.
    - "file"
  - purpose: Literal["assistants", "assistants_output", "batch", 5 more]
    
    The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
    - "assistants"
    - "assistants_output"
    - "batch"
    - "batch_output"
    - "fine-tune"
    - "fine-tune-results"
    - "vision"
    - "user_data"
  - status: Literal["uploaded", "processed", "error"]
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: Optional[int]
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: Optional[str]
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
upload = client.uploads.complete(
    upload_id="upload_abc123",
    part_ids=["string"],
)
print(upload.id)

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "expires_at": 0,
  "filename": "filename",
  "object": "upload",
  "purpose": "purpose",
  "status": "pending",
  "file": {
    "id": "id",
    "bytes": 0,
    "created_at": 0,
    "filename": "filename",
    "object": "file",
    "purpose": "assistants",
    "status": "uploaded",
    "expires_at": 0,
    "status_details": "status_details"
  }
}

Cancel upload

uploads.cancel(strupload_id) -> Upload

post /uploads/{upload_id}/cancel

Cancels the Upload. No Parts may be added after an Upload is cancelled.

Returns the Upload object with status cancelled.

Parameters

upload_id: str

Returns

class Upload: …

The Upload object can accept byte chunks in the form of Parts.
- id: str
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: int
  
  The intended number of bytes to be uploaded.
- created_at: int
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: int
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: str
  
  The name of the file to be uploaded.
- object: Literal["upload"]
  
  The object type, which is always "upload".
  - "upload"
- purpose: str
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: Literal["pending", "completed", "cancelled", "expired"]
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: Optional[FileObject]
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: str
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: int
    
    The size of the file, in bytes.
  - created_at: int
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: str
    
    The name of the file.
  - object: Literal["file"]
    
    The object type, which is always file.
    - "file"
  - purpose: Literal["assistants", "assistants_output", "batch", 5 more]
    
    The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
    - "assistants"
    - "assistants_output"
    - "batch"
    - "batch_output"
    - "fine-tune"
    - "fine-tune-results"
    - "vision"
    - "user_data"
  - status: Literal["uploaded", "processed", "error"]
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: Optional[int]
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: Optional[str]
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
upload = client.uploads.cancel(
    "upload_abc123",
)
print(upload.id)

Response

{
  "id": "id",
  "bytes": 0,
  "created_at": 0,
  "expires_at": 0,
  "filename": "filename",
  "object": "upload",
  "purpose": "purpose",
  "status": "pending",
  "file": {
    "id": "id",
    "bytes": 0,
    "created_at": 0,
    "filename": "filename",
    "object": "file",
    "purpose": "assistants",
    "status": "uploaded",
    "expires_at": 0,
    "status_details": "status_details"
  }
}

Domain Types

Upload

class Upload: …

The Upload object can accept byte chunks in the form of Parts.
- id: str
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: int
  
  The intended number of bytes to be uploaded.
- created_at: int
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: int
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: str
  
  The name of the file to be uploaded.
- object: Literal["upload"]
  
  The object type, which is always "upload".
  - "upload"
- purpose: str
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: Literal["pending", "completed", "cancelled", "expired"]
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: Optional[FileObject]
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: str
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: int
    
    The size of the file, in bytes.
  - created_at: int
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: str
    
    The name of the file.
  - object: Literal["file"]
    
    The object type, which is always file.
    - "file"
  - purpose: Literal["assistants", "assistants_output", "batch", 5 more]
    
    The intended purpose of the file. Supported values are assistants, assistants_output, batch, batch_output, fine-tune, fine-tune-results, vision, and user_data.
    - "assistants"
    - "assistants_output"
    - "batch"
    - "batch_output"
    - "fine-tune"
    - "fine-tune-results"
    - "vision"
    - "user_data"
  - status: Literal["uploaded", "processed", "error"]
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: Optional[int]
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: Optional[str]
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Parts

Add upload part

uploads.parts.create(strupload_id, PartCreateParams**kwargs) -> UploadPart

post /uploads/{upload_id}/parts

Adds a Part to an Upload object. A Part represents a chunk of bytes from the file you are trying to upload.

Each Part can be at most 64 MB, and you can add Parts until you hit the Upload maximum of 8 GB.

It is possible to add multiple Parts in parallel. You can decide the intended order of the Parts when you complete the Upload.

Parameters

upload_id: str
data: FileTypes

The chunk of bytes for this Part.

Returns

class UploadPart: …

The upload Part represents a chunk of bytes we can add to an Upload object.
- id: str
  
  The upload Part unique identifier, which can be referenced in API endpoints.
- created_at: int
  
  The Unix timestamp (in seconds) for when the Part was created.
- object: Literal["upload.part"]
  
  The object type, which is always upload.part.
  - "upload.part"
- upload_id: str
  
  The ID of the Upload object that this Part was added to.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
upload_part = client.uploads.parts.create(
    upload_id="upload_abc123",
    data=b"Example data",
)
print(upload_part.id)

Response

{
  "id": "id",
  "created_at": 0,
  "object": "upload.part",
  "upload_id": "upload_id"
}

Domain Types

Upload Part

class UploadPart: …

The upload Part represents a chunk of bytes we can add to an Upload object.
- id: str
  
  The upload Part unique identifier, which can be referenced in API endpoints.
- created_at: int
  
  The Unix timestamp (in seconds) for when the Part was created.
- object: Literal["upload.part"]
  
  The object type, which is always upload.part.
  - "upload.part"
- upload_id: str
  
  The ID of the Upload object that this Part was added to.

python/resources/uploads/index.md +794 −0 created

1# Uploads

3## Create upload

5`uploads.create(UploadCreateParams**kwargs) -> Upload`

7**post** `/uploads`

9Creates an intermediate [Upload](https://platform.openai.com/docs/api-reference/uploads/object) object

10that you can add [Parts](https://platform.openai.com/docs/api-reference/uploads/part-object) to.

11Currently, an Upload can accept at most 8 GB in total and expires after an

12hour after you create it.

14Once you complete the Upload, we will create a

15[File](https://platform.openai.com/docs/api-reference/files/object) object that contains all the parts

16you uploaded. This File is usable in the rest of our platform as a regular

17File object.

19For certain `purpose` values, the correct `mime_type` must be specified.

20Please refer to documentation for the

21[supported MIME types for your use case](https://platform.openai.com/docs/assistants/tools/file-search#supported-files).

23For guidance on the proper filename extensions for each purpose, please

24follow the documentation on [creating a

25File](https://platform.openai.com/docs/api-reference/files/create).

27Returns the Upload object with status `pending`.

29### Parameters

31- `bytes: int`

33 The number of bytes in the file you are uploading.

35- `filename: str`

37 The name of the file to upload.

39- `mime_type: str`

41 The MIME type of the file.

43 This must fall within the supported MIME types for your file purpose. See

44 the supported MIME types for assistants and vision.

46- `purpose: FilePurpose`

48 The intended purpose of the uploaded file.

50 See the [documentation on File

51 purposes](https://platform.openai.com/docs/api-reference/files/create#files-create-purpose).

53 - `"assistants"`

55 - `"batch"`

57 - `"fine-tune"`

59 - `"vision"`

61 - `"user_data"`

63 - `"evals"`

65- `expires_after: Optional[ExpiresAfter]`

67 The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.

69 - `anchor: Literal["created_at"]`

71 Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.

73 - `"created_at"`

75 - `seconds: int`

77 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).

79### Returns

81- `class Upload: …`

83 The Upload object can accept byte chunks in the form of Parts.

85 - `id: str`

87 The Upload unique identifier, which can be referenced in API endpoints.

89 - `bytes: int`

91 The intended number of bytes to be uploaded.

93 - `created_at: int`

95 The Unix timestamp (in seconds) for when the Upload was created.

97 - `expires_at: int`

99 The Unix timestamp (in seconds) for when the Upload will expire.

100

101 - `filename: str`

102

103 The name of the file to be uploaded.

104

105 - `object: Literal["upload"]`

106

107 The object type, which is always "upload".

108

109 - `"upload"`

110

111 - `purpose: str`

112

113 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.

114

115 - `status: Literal["pending", "completed", "cancelled", "expired"]`

116

117 The status of the Upload.

118

119 - `"pending"`

120

121 - `"completed"`

122

123 - `"cancelled"`

124

125 - `"expired"`

126

127 - `file: Optional[FileObject]`

128

129 The `File` object represents a document that has been uploaded to OpenAI.

130

131 - `id: str`

132

133 The file identifier, which can be referenced in the API endpoints.

134

135 - `bytes: int`

136

137 The size of the file, in bytes.

138

139 - `created_at: int`

140

141 The Unix timestamp (in seconds) for when the file was created.

142

143 - `filename: str`

144

145 The name of the file.

146

147 - `object: Literal["file"]`

148

149 The object type, which is always `file`.

150

151 - `"file"`

152

153 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`

154

155 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

156

157 - `"assistants"`

158

159 - `"assistants_output"`

160

161 - `"batch"`

162

163 - `"batch_output"`

164

165 - `"fine-tune"`

166

167 - `"fine-tune-results"`

168

169 - `"vision"`

170

171 - `"user_data"`

172

173 - `status: Literal["uploaded", "processed", "error"]`

174

175 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

176

177 - `"uploaded"`

178

179 - `"processed"`

180

181 - `"error"`

182

183 - `expires_at: Optional[int]`

184

185 The Unix timestamp (in seconds) for when the file will expire.

186

187 - `status_details: Optional[str]`

188

189 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

190

191### Example

192

193```python

194import os

195from openai import OpenAI

196

197client = OpenAI(

198 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

199)

200upload = client.uploads.create(

201 bytes=0,

202 filename="filename",

203 mime_type="mime_type",

204 purpose="assistants",

205)

206print(upload.id)

207```

208

209#### Response

210

211```json

212{

213 "id": "id",

214 "bytes": 0,

215 "created_at": 0,

216 "expires_at": 0,

217 "filename": "filename",

218 "object": "upload",

219 "purpose": "purpose",

220 "status": "pending",

221 "file": {

222 "id": "id",

223 "bytes": 0,

224 "created_at": 0,

225 "filename": "filename",

226 "object": "file",

227 "purpose": "assistants",

228 "status": "uploaded",

229 "expires_at": 0,

230 "status_details": "status_details"

231 }

232}

233```

234

235## Complete upload

236

237`uploads.complete(strupload_id, UploadCompleteParams**kwargs) -> Upload`

238

239**post** `/uploads/{upload_id}/complete`

240

241Completes the [Upload](https://platform.openai.com/docs/api-reference/uploads/object).

242

243Within the returned Upload object, there is a nested [File](https://platform.openai.com/docs/api-reference/files/object) object that is ready to use in the rest of the platform.

244

245You can specify the order of the Parts by passing in an ordered list of the Part IDs.

246

247The number of bytes uploaded upon completion must match the number of bytes initially specified when creating the Upload object. No Parts may be added after an Upload is completed.

248Returns the Upload object with status `completed`, including an additional `file` property containing the created usable File object.

249

250### Parameters

251

252- `upload_id: str`

253

254- `part_ids: Sequence[str]`

255

256 The ordered list of Part IDs.

257

258- `md5: Optional[str]`

259

260 The optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.

261

262### Returns

263

264- `class Upload: …`

265

266 The Upload object can accept byte chunks in the form of Parts.

267

268 - `id: str`

269

270 The Upload unique identifier, which can be referenced in API endpoints.

271

272 - `bytes: int`

273

274 The intended number of bytes to be uploaded.

275

276 - `created_at: int`

277

278 The Unix timestamp (in seconds) for when the Upload was created.

279

280 - `expires_at: int`

281

282 The Unix timestamp (in seconds) for when the Upload will expire.

283

284 - `filename: str`

285

286 The name of the file to be uploaded.

287

288 - `object: Literal["upload"]`

289

290 The object type, which is always "upload".

291

292 - `"upload"`

293

294 - `purpose: str`

295

296 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.

297

298 - `status: Literal["pending", "completed", "cancelled", "expired"]`

299

300 The status of the Upload.

301

302 - `"pending"`

303

304 - `"completed"`

305

306 - `"cancelled"`

307

308 - `"expired"`

309

310 - `file: Optional[FileObject]`

311

312 The `File` object represents a document that has been uploaded to OpenAI.

313

314 - `id: str`

315

316 The file identifier, which can be referenced in the API endpoints.

317

318 - `bytes: int`

319

320 The size of the file, in bytes.

321

322 - `created_at: int`

323

324 The Unix timestamp (in seconds) for when the file was created.

325

326 - `filename: str`

327

328 The name of the file.

329

330 - `object: Literal["file"]`

331

332 The object type, which is always `file`.

333

334 - `"file"`

335

336 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`

337

338 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

339

340 - `"assistants"`

341

342 - `"assistants_output"`

343

344 - `"batch"`

345

346 - `"batch_output"`

347

348 - `"fine-tune"`

349

350 - `"fine-tune-results"`

351

352 - `"vision"`

353

354 - `"user_data"`

355

356 - `status: Literal["uploaded", "processed", "error"]`

357

358 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

359

360 - `"uploaded"`

361

362 - `"processed"`

363

364 - `"error"`

365

366 - `expires_at: Optional[int]`

367

368 The Unix timestamp (in seconds) for when the file will expire.

369

370 - `status_details: Optional[str]`

371

372 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

373

374### Example

375

376```python

377import os

378from openai import OpenAI

379

380client = OpenAI(

381 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

382)

383upload = client.uploads.complete(

384 upload_id="upload_abc123",

385 part_ids=["string"],

386)

387print(upload.id)

388```

389

390#### Response

391

392```json

393{

394 "id": "id",

395 "bytes": 0,

396 "created_at": 0,

397 "expires_at": 0,

398 "filename": "filename",

399 "object": "upload",

400 "purpose": "purpose",

401 "status": "pending",

402 "file": {

403 "id": "id",

404 "bytes": 0,

405 "created_at": 0,

406 "filename": "filename",

407 "object": "file",

408 "purpose": "assistants",

409 "status": "uploaded",

410 "expires_at": 0,

411 "status_details": "status_details"

412 }

413}

414```

415

416## Cancel upload

417

418`uploads.cancel(strupload_id) -> Upload`

419

420**post** `/uploads/{upload_id}/cancel`

421

422Cancels the Upload. No Parts may be added after an Upload is cancelled.

423

424Returns the Upload object with status `cancelled`.

425

426### Parameters

427

428- `upload_id: str`

429

430### Returns

431

432- `class Upload: …`

433

434 The Upload object can accept byte chunks in the form of Parts.

435

436 - `id: str`

437

438 The Upload unique identifier, which can be referenced in API endpoints.

439

440 - `bytes: int`

441

442 The intended number of bytes to be uploaded.

443

444 - `created_at: int`

445

446 The Unix timestamp (in seconds) for when the Upload was created.

447

448 - `expires_at: int`

449

450 The Unix timestamp (in seconds) for when the Upload will expire.

451

452 - `filename: str`

453

454 The name of the file to be uploaded.

455

456 - `object: Literal["upload"]`

457

458 The object type, which is always "upload".

459

460 - `"upload"`

461

462 - `purpose: str`

463

464 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.

465

466 - `status: Literal["pending", "completed", "cancelled", "expired"]`

467

468 The status of the Upload.

469

470 - `"pending"`

471

472 - `"completed"`

473

474 - `"cancelled"`

475

476 - `"expired"`

477

478 - `file: Optional[FileObject]`

479

480 The `File` object represents a document that has been uploaded to OpenAI.

481

482 - `id: str`

483

484 The file identifier, which can be referenced in the API endpoints.

485

486 - `bytes: int`

487

488 The size of the file, in bytes.

489

490 - `created_at: int`

491

492 The Unix timestamp (in seconds) for when the file was created.

493

494 - `filename: str`

495

496 The name of the file.

497

498 - `object: Literal["file"]`

499

500 The object type, which is always `file`.

501

502 - `"file"`

503

504 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`

505

506 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

507

508 - `"assistants"`

509

510 - `"assistants_output"`

511

512 - `"batch"`

513

514 - `"batch_output"`

515

516 - `"fine-tune"`

517

518 - `"fine-tune-results"`

519

520 - `"vision"`

521

522 - `"user_data"`

523

524 - `status: Literal["uploaded", "processed", "error"]`

525

526 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

527

528 - `"uploaded"`

529

530 - `"processed"`

531

532 - `"error"`

533

534 - `expires_at: Optional[int]`

535

536 The Unix timestamp (in seconds) for when the file will expire.

537

538 - `status_details: Optional[str]`

539

540 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

541

542### Example

543

544```python

545import os

546from openai import OpenAI

547

548client = OpenAI(

549 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

550)

551upload = client.uploads.cancel(

552 "upload_abc123",

553)

554print(upload.id)

555```

556

557#### Response

558

559```json

560{

561 "id": "id",

562 "bytes": 0,

563 "created_at": 0,

564 "expires_at": 0,

565 "filename": "filename",

566 "object": "upload",

567 "purpose": "purpose",

568 "status": "pending",

569 "file": {

570 "id": "id",

571 "bytes": 0,

572 "created_at": 0,

573 "filename": "filename",

574 "object": "file",

575 "purpose": "assistants",

576 "status": "uploaded",

577 "expires_at": 0,

578 "status_details": "status_details"

579 }

580}

581```

582

583## Domain Types

584

585### Upload

586

587- `class Upload: …`

588

589 The Upload object can accept byte chunks in the form of Parts.

590

591 - `id: str`

592

593 The Upload unique identifier, which can be referenced in API endpoints.

594

595 - `bytes: int`

596

597 The intended number of bytes to be uploaded.

598

599 - `created_at: int`

600

601 The Unix timestamp (in seconds) for when the Upload was created.

602

603 - `expires_at: int`

604

605 The Unix timestamp (in seconds) for when the Upload will expire.

606

607 - `filename: str`

608

609 The name of the file to be uploaded.

610

611 - `object: Literal["upload"]`

612

613 The object type, which is always "upload".

614

615 - `"upload"`

616

617 - `purpose: str`

618

619 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.

620

621 - `status: Literal["pending", "completed", "cancelled", "expired"]`

622

623 The status of the Upload.

624

625 - `"pending"`

626

627 - `"completed"`

628

629 - `"cancelled"`

630

631 - `"expired"`

632

633 - `file: Optional[FileObject]`

634

635 The `File` object represents a document that has been uploaded to OpenAI.

636

637 - `id: str`

638

639 The file identifier, which can be referenced in the API endpoints.

640

641 - `bytes: int`

642

643 The size of the file, in bytes.

644

645 - `created_at: int`

646

647 The Unix timestamp (in seconds) for when the file was created.

648

649 - `filename: str`

650

651 The name of the file.

652

653 - `object: Literal["file"]`

654

655 The object type, which is always `file`.

656

657 - `"file"`

658

659 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`

660

661 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.

662

663 - `"assistants"`

664

665 - `"assistants_output"`

666

667 - `"batch"`

668

669 - `"batch_output"`

670

671 - `"fine-tune"`

672

673 - `"fine-tune-results"`

674

675 - `"vision"`

676

677 - `"user_data"`

678

679 - `status: Literal["uploaded", "processed", "error"]`

680

681 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.

682

683 - `"uploaded"`

684

685 - `"processed"`

686

687 - `"error"`

688

689 - `expires_at: Optional[int]`

690

691 The Unix timestamp (in seconds) for when the file will expire.

692

693 - `status_details: Optional[str]`

694

695 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.

696

697# Parts

698

699## Add upload part

700

701`uploads.parts.create(strupload_id, PartCreateParams**kwargs) -> UploadPart`

702

703**post** `/uploads/{upload_id}/parts`

704

705Adds a [Part](https://platform.openai.com/docs/api-reference/uploads/part-object) to an [Upload](https://platform.openai.com/docs/api-reference/uploads/object) object. A Part represents a chunk of bytes from the file you are trying to upload.

706

707Each Part can be at most 64 MB, and you can add Parts until you hit the Upload maximum of 8 GB.

708

709It is possible to add multiple Parts in parallel. You can decide the intended order of the Parts when you [complete the Upload](https://platform.openai.com/docs/api-reference/uploads/complete).

710

711### Parameters

712

713- `upload_id: str`

714

715- `data: FileTypes`

716

717 The chunk of bytes for this Part.

718

719### Returns

720

721- `class UploadPart: …`

722

723 The upload Part represents a chunk of bytes we can add to an Upload object.

724

725 - `id: str`

726

727 The upload Part unique identifier, which can be referenced in API endpoints.

728

729 - `created_at: int`

730

731 The Unix timestamp (in seconds) for when the Part was created.

732

733 - `object: Literal["upload.part"]`

734

735 The object type, which is always `upload.part`.

736

737 - `"upload.part"`

738

739 - `upload_id: str`

740

741 The ID of the Upload object that this Part was added to.

742

743### Example

744

745```python

746import os

747from openai import OpenAI

748

749client = OpenAI(

750 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted

751)

752upload_part = client.uploads.parts.create(

753 upload_id="upload_abc123",

754 data=b"Example data",

755)

756print(upload_part.id)

757```

758

759#### Response

760

761```json

762{

763 "id": "id",

764 "created_at": 0,

765 "object": "upload.part",

766 "upload_id": "upload_id"

767}

768```

769

770## Domain Types

771

772### Upload Part

773

774- `class UploadPart: …`

775

776 The upload Part represents a chunk of bytes we can add to an Upload object.

777

778 - `id: str`

779

780 The upload Part unique identifier, which can be referenced in API endpoints.

781

782 - `created_at: int`

783

784 The Unix timestamp (in seconds) for when the Part was created.

785

786 - `object: Literal["upload.part"]`

787

788 The object type, which is always `upload.part`.

789

790 - `"upload.part"`

791

792 - `upload_id: str`

793

794 The ID of the Upload object that this Part was added to.

python/resources/uploads/index.md 2026-05-02 05:57 UTC to 2026-05-05 23:00 UTC

Uploads

Create upload

Parameters

Returns

Example

Response

Complete upload

Parameters

Returns

Example

Response

Cancel upload

Parameters

Returns

Example

Response

Domain Types

Upload

Parts

Add upload part

Parameters

Returns

Example

Response

Domain Types

Upload Part