Uploads

Create upload

$ openai uploads create

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

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

The name of the file to upload.
--mime-type: string

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: "assistants" or "batch" or "fine-tune" or 3 more

The intended purpose of the uploaded file.

See the documentation on File purposes.
--expires-after: optional object { anchor, seconds }

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.

Returns

upload: object { id, bytes, created_at, 6 more }

The Upload object can accept byte chunks in the form of Parts.
- id: string
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: number
  
  The intended number of bytes to be uploaded.
- created_at: number
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: number
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: string
  
  The name of the file to be uploaded.
- object: "upload"
  
  The object type, which is always "upload".
- purpose: string
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: "pending" or "completed" or "cancelled" or "expired"
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: optional object { id, bytes, created_at, 6 more }
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: string
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: number
    
    The size of the file, in bytes.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: string
    
    The name of the file.
  - object: "file"
    
    The object type, which is always file.
  - purpose: "assistants" or "assistants_output" or "batch" or 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: "uploaded" or "processed" or "error"
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: optional number
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: optional string
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

openai uploads create \
  --api-key 'My API Key' \
  --bytes 0 \
  --filename filename \
  --mime-type mime_type \
  --purpose assistants

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

$ openai uploads complete

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

The ID of the Upload.
--part-id: array of string

The ordered list of Part IDs.
--md5: optional string

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

Returns

upload: object { id, bytes, created_at, 6 more }

The Upload object can accept byte chunks in the form of Parts.
- id: string
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: number
  
  The intended number of bytes to be uploaded.
- created_at: number
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: number
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: string
  
  The name of the file to be uploaded.
- object: "upload"
  
  The object type, which is always "upload".
- purpose: string
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: "pending" or "completed" or "cancelled" or "expired"
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: optional object { id, bytes, created_at, 6 more }
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: string
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: number
    
    The size of the file, in bytes.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: string
    
    The name of the file.
  - object: "file"
    
    The object type, which is always file.
  - purpose: "assistants" or "assistants_output" or "batch" or 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: "uploaded" or "processed" or "error"
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: optional number
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: optional string
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

openai uploads complete \
  --api-key 'My API Key' \
  --upload-id upload_abc123 \
  --part-id string

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

$ openai uploads cancel

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

The ID of the Upload.

Returns

upload: object { id, bytes, created_at, 6 more }

The Upload object can accept byte chunks in the form of Parts.
- id: string
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: number
  
  The intended number of bytes to be uploaded.
- created_at: number
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: number
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: string
  
  The name of the file to be uploaded.
- object: "upload"
  
  The object type, which is always "upload".
- purpose: string
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: "pending" or "completed" or "cancelled" or "expired"
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: optional object { id, bytes, created_at, 6 more }
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: string
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: number
    
    The size of the file, in bytes.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: string
    
    The name of the file.
  - object: "file"
    
    The object type, which is always file.
  - purpose: "assistants" or "assistants_output" or "batch" or 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: "uploaded" or "processed" or "error"
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: optional number
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: optional string
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Example

openai uploads cancel \
  --api-key 'My API Key' \
  --upload-id upload_abc123

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

upload: object { id, bytes, created_at, 6 more }

The Upload object can accept byte chunks in the form of Parts.
- id: string
  
  The Upload unique identifier, which can be referenced in API endpoints.
- bytes: number
  
  The intended number of bytes to be uploaded.
- created_at: number
  
  The Unix timestamp (in seconds) for when the Upload was created.
- expires_at: number
  
  The Unix timestamp (in seconds) for when the Upload will expire.
- filename: string
  
  The name of the file to be uploaded.
- object: "upload"
  
  The object type, which is always "upload".
- purpose: string
  
  The intended purpose of the file. Please refer here for acceptable values.
- status: "pending" or "completed" or "cancelled" or "expired"
  
  The status of the Upload.
  - "pending"
  - "completed"
  - "cancelled"
  - "expired"
- file: optional object { id, bytes, created_at, 6 more }
  
  The File object represents a document that has been uploaded to OpenAI.
  - id: string
    
    The file identifier, which can be referenced in the API endpoints.
  - bytes: number
    
    The size of the file, in bytes.
  - created_at: number
    
    The Unix timestamp (in seconds) for when the file was created.
  - filename: string
    
    The name of the file.
  - object: "file"
    
    The object type, which is always file.
  - purpose: "assistants" or "assistants_output" or "batch" or 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: "uploaded" or "processed" or "error"
    
    Deprecated. The current status of the file, which can be either uploaded, processed, or error.
    - "uploaded"
    - "processed"
    - "error"
  - expires_at: optional number
    
    The Unix timestamp (in seconds) for when the file will expire.
  - status_details: optional string
    
    Deprecated. For details on why a fine-tuning training file failed validation, see the error field on fine_tuning.job.

Parts

Add upload part

$ openai uploads:parts create

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

The ID of the Upload.
--data: string

The chunk of bytes for this Part.

Returns

upload_part: object { id, created_at, object, upload_id }

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

Example

openai uploads:parts create \
  --api-key 'My API Key' \
  --upload-id upload_abc123 \
  --data 'Example data'

Response

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

Domain Types

Upload Part

upload_part: object { id, created_at, object, upload_id }

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

cli/resources/uploads/index.md +730 −0 created

1# Uploads

3## Create upload

5`$ openai uploads create`

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: number`

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

35- `--filename: string`

37 The name of the file to upload.

39- `--mime-type: string`

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: "assistants" or "batch" or "fine-tune" or 3 more`

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- `--expires-after: optional object { anchor, seconds }`

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

57### Returns

59- `upload: object { id, bytes, created_at, 6 more }`

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

63 - `id: string`

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

67 - `bytes: number`

69 The intended number of bytes to be uploaded.

71 - `created_at: number`

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

75 - `expires_at: number`

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

79 - `filename: string`

81 The name of the file to be uploaded.

83 - `object: "upload"`

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

87 - `purpose: string`

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

91 - `status: "pending" or "completed" or "cancelled" or "expired"`

93 The status of the Upload.

95 - `"pending"`

97 - `"completed"`

99 - `"cancelled"`

100

101 - `"expired"`

102

103 - `file: optional object { id, bytes, created_at, 6 more }`

104

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

106

107 - `id: string`

108

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

110

111 - `bytes: number`

112

113 The size of the file, in bytes.

114

115 - `created_at: number`

116

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

118

119 - `filename: string`

120

121 The name of the file.

122

123 - `object: "file"`

124

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

126

127 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`

128

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

130

131 - `"assistants"`

132

133 - `"assistants_output"`

134

135 - `"batch"`

136

137 - `"batch_output"`

138

139 - `"fine-tune"`

140

141 - `"fine-tune-results"`

142

143 - `"vision"`

144

145 - `"user_data"`

146

147 - `status: "uploaded" or "processed" or "error"`

148

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

150

151 - `"uploaded"`

152

153 - `"processed"`

154

155 - `"error"`

156

157 - `expires_at: optional number`

158

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

160

161 - `status_details: optional string`

162

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

164

165### Example

166

167```cli

168openai uploads create \

169 --api-key 'My API Key' \

170 --bytes 0 \

171 --filename filename \

172 --mime-type mime_type \

173 --purpose assistants

174```

175

176#### Response

177

178```json

179{

180 "id": "id",

181 "bytes": 0,

182 "created_at": 0,

183 "expires_at": 0,

184 "filename": "filename",

185 "object": "upload",

186 "purpose": "purpose",

187 "status": "pending",

188 "file": {

189 "id": "id",

190 "bytes": 0,

191 "created_at": 0,

192 "filename": "filename",

193 "object": "file",

194 "purpose": "assistants",

195 "status": "uploaded",

196 "expires_at": 0,

197 "status_details": "status_details"

198 }

199}

200```

201

202## Complete upload

203

204`$ openai uploads complete`

205

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

207

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

209

210Within 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.

211

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

213

214The 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.

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

216

217### Parameters

218

219- `--upload-id: string`

220

221 The ID of the Upload.

222

223- `--part-id: array of string`

224

225 The ordered list of Part IDs.

226

227- `--md5: optional string`

228

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

230

231### Returns

232

233- `upload: object { id, bytes, created_at, 6 more }`

234

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

236

237 - `id: string`

238

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

240

241 - `bytes: number`

242

243 The intended number of bytes to be uploaded.

244

245 - `created_at: number`

246

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

248

249 - `expires_at: number`

250

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

252

253 - `filename: string`

254

255 The name of the file to be uploaded.

256

257 - `object: "upload"`

258

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

260

261 - `purpose: string`

262

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

264

265 - `status: "pending" or "completed" or "cancelled" or "expired"`

266

267 The status of the Upload.

268

269 - `"pending"`

270

271 - `"completed"`

272

273 - `"cancelled"`

274

275 - `"expired"`

276

277 - `file: optional object { id, bytes, created_at, 6 more }`

278

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

280

281 - `id: string`

282

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

284

285 - `bytes: number`

286

287 The size of the file, in bytes.

288

289 - `created_at: number`

290

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

292

293 - `filename: string`

294

295 The name of the file.

296

297 - `object: "file"`

298

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

300

301 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`

302

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

304

305 - `"assistants"`

306

307 - `"assistants_output"`

308

309 - `"batch"`

310

311 - `"batch_output"`

312

313 - `"fine-tune"`

314

315 - `"fine-tune-results"`

316

317 - `"vision"`

318

319 - `"user_data"`

320

321 - `status: "uploaded" or "processed" or "error"`

322

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

324

325 - `"uploaded"`

326

327 - `"processed"`

328

329 - `"error"`

330

331 - `expires_at: optional number`

332

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

334

335 - `status_details: optional string`

336

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

338

339### Example

340

341```cli

342openai uploads complete \

343 --api-key 'My API Key' \

344 --upload-id upload_abc123 \

345 --part-id string

346```

347

348#### Response

349

350```json

351{

352 "id": "id",

353 "bytes": 0,

354 "created_at": 0,

355 "expires_at": 0,

356 "filename": "filename",

357 "object": "upload",

358 "purpose": "purpose",

359 "status": "pending",

360 "file": {

361 "id": "id",

362 "bytes": 0,

363 "created_at": 0,

364 "filename": "filename",

365 "object": "file",

366 "purpose": "assistants",

367 "status": "uploaded",

368 "expires_at": 0,

369 "status_details": "status_details"

370 }

371}

372```

373

374## Cancel upload

375

376`$ openai uploads cancel`

377

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

379

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

381

382Returns the Upload object with status `cancelled`.

383

384### Parameters

385

386- `--upload-id: string`

387

388 The ID of the Upload.

389

390### Returns

391

392- `upload: object { id, bytes, created_at, 6 more }`

393

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

395

396 - `id: string`

397

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

399

400 - `bytes: number`

401

402 The intended number of bytes to be uploaded.

403

404 - `created_at: number`

405

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

407

408 - `expires_at: number`

409

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

411

412 - `filename: string`

413

414 The name of the file to be uploaded.

415

416 - `object: "upload"`

417

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

419

420 - `purpose: string`

421

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

423

424 - `status: "pending" or "completed" or "cancelled" or "expired"`

425

426 The status of the Upload.

427

428 - `"pending"`

429

430 - `"completed"`

431

432 - `"cancelled"`

433

434 - `"expired"`

435

436 - `file: optional object { id, bytes, created_at, 6 more }`

437

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

439

440 - `id: string`

441

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

443

444 - `bytes: number`

445

446 The size of the file, in bytes.

447

448 - `created_at: number`

449

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

451

452 - `filename: string`

453

454 The name of the file.

455

456 - `object: "file"`

457

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

459

460 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`

461

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

463

464 - `"assistants"`

465

466 - `"assistants_output"`

467

468 - `"batch"`

469

470 - `"batch_output"`

471

472 - `"fine-tune"`

473

474 - `"fine-tune-results"`

475

476 - `"vision"`

477

478 - `"user_data"`

479

480 - `status: "uploaded" or "processed" or "error"`

481

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

483

484 - `"uploaded"`

485

486 - `"processed"`

487

488 - `"error"`

489

490 - `expires_at: optional number`

491

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

493

494 - `status_details: optional string`

495

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

497

498### Example

499

500```cli

501openai uploads cancel \

502 --api-key 'My API Key' \

503 --upload-id upload_abc123

504```

505

506#### Response

507

508```json

509{

510 "id": "id",

511 "bytes": 0,

512 "created_at": 0,

513 "expires_at": 0,

514 "filename": "filename",

515 "object": "upload",

516 "purpose": "purpose",

517 "status": "pending",

518 "file": {

519 "id": "id",

520 "bytes": 0,

521 "created_at": 0,

522 "filename": "filename",

523 "object": "file",

524 "purpose": "assistants",

525 "status": "uploaded",

526 "expires_at": 0,

527 "status_details": "status_details"

528 }

529}

530```

531

532## Domain Types

533

534### Upload

535

536- `upload: object { id, bytes, created_at, 6 more }`

537

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

539

540 - `id: string`

541

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

543

544 - `bytes: number`

545

546 The intended number of bytes to be uploaded.

547

548 - `created_at: number`

549

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

551

552 - `expires_at: number`

553

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

555

556 - `filename: string`

557

558 The name of the file to be uploaded.

559

560 - `object: "upload"`

561

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

563

564 - `purpose: string`

565

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

567

568 - `status: "pending" or "completed" or "cancelled" or "expired"`

569

570 The status of the Upload.

571

572 - `"pending"`

573

574 - `"completed"`

575

576 - `"cancelled"`

577

578 - `"expired"`

579

580 - `file: optional object { id, bytes, created_at, 6 more }`

581

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

583

584 - `id: string`

585

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

587

588 - `bytes: number`

589

590 The size of the file, in bytes.

591

592 - `created_at: number`

593

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

595

596 - `filename: string`

597

598 The name of the file.

599

600 - `object: "file"`

601

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

603

604 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`

605

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

607

608 - `"assistants"`

609

610 - `"assistants_output"`

611

612 - `"batch"`

613

614 - `"batch_output"`

615

616 - `"fine-tune"`

617

618 - `"fine-tune-results"`

619

620 - `"vision"`

621

622 - `"user_data"`

623

624 - `status: "uploaded" or "processed" or "error"`

625

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

627

628 - `"uploaded"`

629

630 - `"processed"`

631

632 - `"error"`

633

634 - `expires_at: optional number`

635

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

637

638 - `status_details: optional string`

639

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

641

642# Parts

643

644## Add upload part

645

646`$ openai uploads:parts create`

647

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

649

650Adds 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.

651

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

653

654It 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).

655

656### Parameters

657

658- `--upload-id: string`

659

660 The ID of the Upload.

661

662- `--data: string`

663

664 The chunk of bytes for this Part.

665

666### Returns

667

668- `upload_part: object { id, created_at, object, upload_id }`

669

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

671

672 - `id: string`

673

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

675

676 - `created_at: number`

677

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

679

680 - `object: "upload.part"`

681

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

683

684 - `upload_id: string`

685

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

687

688### Example

689

690```cli

691openai uploads:parts create \

692 --api-key 'My API Key' \

693 --upload-id upload_abc123 \

694 --data 'Example data'

695```

696

697#### Response

698

699```json

700{

701 "id": "id",

702 "created_at": 0,

703 "object": "upload.part",

704 "upload_id": "upload_id"

705}

706```

707

708## Domain Types

709

710### Upload Part

711

712- `upload_part: object { id, created_at, object, upload_id }`

713

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

715

716 - `id: string`

717

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

719

720 - `created_at: number`

721

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

723

724 - `object: "upload.part"`

725

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

727

728 - `upload_id: string`

729

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

cli/resources/uploads/index.md 2026-05-05 23:00 UTC to 2026-05-07 21:57 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