Uploads

Create upload

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

post /uploads

Create upload

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: FilePurposeParam

The intended purpose of the uploaded file.

See the documentation on File purposes.
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={},
)
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

Complete upload

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

Cancel upload

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

Add upload part

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 +751 −0 created

1# Uploads

3## Create upload

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

7**post** `/uploads`

9Create upload

11### Parameters

13- `bytes: int`

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

17- `filename: str`

19 The name of the file to upload.

21- `mime_type: str`

23 The MIME type of the file.

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

26 the supported MIME types for assistants and vision.

28- `purpose: FilePurposeParam`

30 The intended purpose of the uploaded file.

32 See the [documentation on File

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

35- `expires_after: Optional[ExpiresAfter]`

37 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.

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

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

43 - `"created_at"`

45 - `seconds: int`

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

49### Returns

51- `class Upload: …`

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

55 - `id: str`

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

59 - `bytes: int`

61 The intended number of bytes to be uploaded.

63 - `created_at: int`

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

67 - `expires_at: int`

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

71 - `filename: str`

73 The name of the file to be uploaded.

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

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

79 - `"upload"`

81 - `purpose: str`

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

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

87 The status of the Upload.

89 - `"pending"`

91 - `"completed"`

93 - `"cancelled"`

95 - `"expired"`

97 - `file: Optional[FileObject]`

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

100

101 - `id: str`

102

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

104

105 - `bytes: int`

106

107 The size of the file, in bytes.

108

109 - `created_at: int`

110

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

112

113 - `filename: str`

114

115 The name of the file.

116

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

118

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

120

121 - `"file"`

122

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

124

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

126

127 - `"assistants"`

128

129 - `"assistants_output"`

130

131 - `"batch"`

132

133 - `"batch_output"`

134

135 - `"fine-tune"`

136

137 - `"fine-tune-results"`

138

139 - `"vision"`

140

141 - `"user_data"`

142

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

144

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

146

147 - `"uploaded"`

148

149 - `"processed"`

150

151 - `"error"`

152

153 - `expires_at: Optional[int]`

154

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

156

157 - `status_details: Optional[str]`

158

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

160

161### Example

162

163```python

164import os

165from openai import OpenAI

166

167client = OpenAI(

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

169)

170upload = client.uploads.create(

171 bytes=0,

172 filename="filename",

173 mime_type="mime_type",

174 purpose={},

175)

176print(upload.id)

177```

178

179#### Response

180

181```json

182{

183 "id": "id",

184 "bytes": 0,

185 "created_at": 0,

186 "expires_at": 0,

187 "filename": "filename",

188 "object": "upload",

189 "purpose": "purpose",

190 "status": "pending",

191 "file": {

192 "id": "id",

193 "bytes": 0,

194 "created_at": 0,

195 "filename": "filename",

196 "object": "file",

197 "purpose": "assistants",

198 "status": "uploaded",

199 "expires_at": 0,

200 "status_details": "status_details"

201 }

202}

203```

204

205## Complete upload

206

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

208

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

210

211Complete upload

212

213### Parameters

214

215- `upload_id: str`

216

217- `part_ids: Sequence[str]`

218

219 The ordered list of Part IDs.

220

221- `md5: Optional[str]`

222

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

224

225### Returns

226

227- `class Upload: …`

228

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

230

231 - `id: str`

232

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

234

235 - `bytes: int`

236

237 The intended number of bytes to be uploaded.

238

239 - `created_at: int`

240

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

242

243 - `expires_at: int`

244

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

246

247 - `filename: str`

248

249 The name of the file to be uploaded.

250

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

252

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

254

255 - `"upload"`

256

257 - `purpose: str`

258

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

260

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

262

263 The status of the Upload.

264

265 - `"pending"`

266

267 - `"completed"`

268

269 - `"cancelled"`

270

271 - `"expired"`

272

273 - `file: Optional[FileObject]`

274

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

276

277 - `id: str`

278

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

280

281 - `bytes: int`

282

283 The size of the file, in bytes.

284

285 - `created_at: int`

286

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

288

289 - `filename: str`

290

291 The name of the file.

292

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

294

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

296

297 - `"file"`

298

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

300

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

302

303 - `"assistants"`

304

305 - `"assistants_output"`

306

307 - `"batch"`

308

309 - `"batch_output"`

310

311 - `"fine-tune"`

312

313 - `"fine-tune-results"`

314

315 - `"vision"`

316

317 - `"user_data"`

318

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

320

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

322

323 - `"uploaded"`

324

325 - `"processed"`

326

327 - `"error"`

328

329 - `expires_at: Optional[int]`

330

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

332

333 - `status_details: Optional[str]`

334

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

336

337### Example

338

339```python

340import os

341from openai import OpenAI

342

343client = OpenAI(

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

345)

346upload = client.uploads.complete(

347 upload_id="upload_abc123",

348 part_ids=["string"],

349)

350print(upload.id)

351```

352

353#### Response

354

355```json

356{

357 "id": "id",

358 "bytes": 0,

359 "created_at": 0,

360 "expires_at": 0,

361 "filename": "filename",

362 "object": "upload",

363 "purpose": "purpose",

364 "status": "pending",

365 "file": {

366 "id": "id",

367 "bytes": 0,

368 "created_at": 0,

369 "filename": "filename",

370 "object": "file",

371 "purpose": "assistants",

372 "status": "uploaded",

373 "expires_at": 0,

374 "status_details": "status_details"

375 }

376}

377```

378

379## Cancel upload

380

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

382

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

384

385Cancel upload

386

387### Parameters

388

389- `upload_id: str`

390

391### Returns

392

393- `class Upload: …`

394

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

396

397 - `id: str`

398

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

400

401 - `bytes: int`

402

403 The intended number of bytes to be uploaded.

404

405 - `created_at: int`

406

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

408

409 - `expires_at: int`

410

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

412

413 - `filename: str`

414

415 The name of the file to be uploaded.

416

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

418

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

420

421 - `"upload"`

422

423 - `purpose: str`

424

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

426

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

428

429 The status of the Upload.

430

431 - `"pending"`

432

433 - `"completed"`

434

435 - `"cancelled"`

436

437 - `"expired"`

438

439 - `file: Optional[FileObject]`

440

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

442

443 - `id: str`

444

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

446

447 - `bytes: int`

448

449 The size of the file, in bytes.

450

451 - `created_at: int`

452

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

454

455 - `filename: str`

456

457 The name of the file.

458

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

460

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

462

463 - `"file"`

464

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

466

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

468

469 - `"assistants"`

470

471 - `"assistants_output"`

472

473 - `"batch"`

474

475 - `"batch_output"`

476

477 - `"fine-tune"`

478

479 - `"fine-tune-results"`

480

481 - `"vision"`

482

483 - `"user_data"`

484

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

486

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

488

489 - `"uploaded"`

490

491 - `"processed"`

492

493 - `"error"`

494

495 - `expires_at: Optional[int]`

496

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

498

499 - `status_details: Optional[str]`

500

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

502

503### Example

504

505```python

506import os

507from openai import OpenAI

508

509client = OpenAI(

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

511)

512upload = client.uploads.cancel(

513 "upload_abc123",

514)

515print(upload.id)

516```

517

518#### Response

519

520```json

521{

522 "id": "id",

523 "bytes": 0,

524 "created_at": 0,

525 "expires_at": 0,

526 "filename": "filename",

527 "object": "upload",

528 "purpose": "purpose",

529 "status": "pending",

530 "file": {

531 "id": "id",

532 "bytes": 0,

533 "created_at": 0,

534 "filename": "filename",

535 "object": "file",

536 "purpose": "assistants",

537 "status": "uploaded",

538 "expires_at": 0,

539 "status_details": "status_details"

540 }

541}

542```

543

544## Domain Types

545

546### Upload

547

548- `class Upload: …`

549

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

551

552 - `id: str`

553

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

555

556 - `bytes: int`

557

558 The intended number of bytes to be uploaded.

559

560 - `created_at: int`

561

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

563

564 - `expires_at: int`

565

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

567

568 - `filename: str`

569

570 The name of the file to be uploaded.

571

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

573

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

575

576 - `"upload"`

577

578 - `purpose: str`

579

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

581

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

583

584 The status of the Upload.

585

586 - `"pending"`

587

588 - `"completed"`

589

590 - `"cancelled"`

591

592 - `"expired"`

593

594 - `file: Optional[FileObject]`

595

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

597

598 - `id: str`

599

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

601

602 - `bytes: int`

603

604 The size of the file, in bytes.

605

606 - `created_at: int`

607

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

609

610 - `filename: str`

611

612 The name of the file.

613

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

615

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

617

618 - `"file"`

619

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

621

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

623

624 - `"assistants"`

625

626 - `"assistants_output"`

627

628 - `"batch"`

629

630 - `"batch_output"`

631

632 - `"fine-tune"`

633

634 - `"fine-tune-results"`

635

636 - `"vision"`

637

638 - `"user_data"`

639

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

641

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

643

644 - `"uploaded"`

645

646 - `"processed"`

647

648 - `"error"`

649

650 - `expires_at: Optional[int]`

651

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

653

654 - `status_details: Optional[str]`

655

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

657

658# Parts

659

660## Add upload part

661

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

663

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

665

666Add upload part

667

668### Parameters

669

670- `upload_id: str`

671

672- `data: FileTypes`

673

674 The chunk of bytes for this Part.

675

676### Returns

677

678- `class UploadPart: …`

679

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

681

682 - `id: str`

683

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

685

686 - `created_at: int`

687

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

689

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

691

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

693

694 - `"upload.part"`

695

696 - `upload_id: str`

697

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

699

700### Example

701

702```python

703import os

704from openai import OpenAI

705

706client = OpenAI(

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

708)

709upload_part = client.uploads.parts.create(

710 upload_id="upload_abc123",

711 data=b"Example data",

712)

713print(upload_part.id)

714```

715

716#### Response

717

718```json

719{

720 "id": "id",

721 "created_at": 0,

722 "object": "upload.part",

723 "upload_id": "upload_id"

724}

725```

726

727## Domain Types

728

729### Upload Part

730

731- `class UploadPart: …`

732

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

734

735 - `id: str`

736

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

738

739 - `created_at: int`

740

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

742

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

744

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

746

747 - `"upload.part"`

748

749 - `upload_id: str`

750

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

python/resources/uploads/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 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