Files and storage
What is kept of a model's output, and for how long: every file, until you delete it.
| What is kept | every file a key sends or gets back: pictures, clips, songs, speech, uploads |
|---|---|
| How long | until you delete it: a kept file never expires |
| As what | byte for byte, as it arrived: never resized or re-encoded |
| What it costs | nothing, to keep or to fetch |
Text, vectors, transcripts, rerank and classification make no file: their answer is the whole of it.
1. Upload a file
POST /v1/files takes one file, sent as a form, in the field file, with your API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →. It answers once the file is kept, with its id. The sample uploads a small catalogue for Souk Bot, then reads the file's details back.
import json
import os
import urllib.request
key = os.environ["OPENDUNES_API_KEY"]
base_url = "https://opendunes.com/v1"
file_name = "catalogue.csv"
boundary = "opendunes-upload"
catalogue = (
"sku,name\n"
"burnous-01,Burnous en laine\n"
"tapis-07,Tapis berbère 200 × 300\n"
).encode()
head = (
f"--{boundary}\r\n"
'Content-Disposition: form-data; name="file"; '
f'filename="{file_name}"\r\n'
"Content-Type: text/csv\r\n\r\n"
).encode()
body = head + catalogue + f"\r\n--{boundary}--\r\n".encode()
upload = urllib.request.Request(
base_url + "/files",
data=body,
headers={
"Authorization": "Bearer " + key,
"Content-Type": "multipart/form-data; boundary=" + boundary,
},
)
with urllib.request.urlopen(upload) as response:
uploaded = json.load(response)
read = urllib.request.Request(
base_url + "/files/" + uploaded["id"],
headers={"Authorization": "Bearer " + key},
)
with urllib.request.urlopen(read) as response:
details = json.load(response)
print(details["id"], details["filename"], details["downloadable"])| Field | Holds |
|---|---|
id | the file's ID, such as 3f6c2a9e-8b1d-4e7a-9c5f-2d4b6a8e1c07 |
filename | the name it was sent with |
mime_type | what the file is, read from its bytes |
size_bytes | its size |
created_at | when it was kept |
downloadable | true once its copy is kept; false until then |
An upload is kept whatever the key's storage setting.
2. Use it in a request
A kept file goes into a request by its ID, in place of its bytes. In a conversation, it is a content part:
{
"type": "file",
"file": {
"file_id": "3f6c2a9e-8b1d-4e7a-9c5f-2d4b6a8e1c07"
}
}Each route that reads files says where the ID goes: Chat, Picture generation, Clips.
3. Find what a model made
Every file a model makes for your key lands in Files, under its own ID, and the answer names it.
| The answer | Carries the ID |
|---|---|
| a picture, a song or a spoken reply inside the answer | file_id, beside each file, one per file, in order |
| the file itself as raw bytes, such as speech | the header X-File-Id |
A picture, as it comes back, illustrative:
{
"created": 1758635520,
"data": [
{
"b64_json": "iVBORw0KGgo…",
"media_type": "image/png",
"file_id": "3f6c2a9e-8b1d-4e7a-9c5f-2d4b6a8e1c07"
}
]
}A file is listed the moment the answer is delivered. Until its copy is kept, it reads downloadable: false; you already hold the bytes the answer carried.
Some answers carry an expires_at. It is the provider's clock, for the provider's copy. The copy in Files never expires.
4. Delete a file
DELETE /v1/files/{id} deletes the file.
A delete cannot be undone: no route brings the file back. If you may need it, download it first with GET /v1/files/{id}/content.
Its charge stays in your history: deleting a file never touches what the request that made it cost.
| You delete | Goes |
|---|---|
| a file, from Files or the Storage page | that file |
| a conversation in the chat | every file in it |
| your account | every file, at once |
Keep nothing on a key
Every key keeps by default. Storage is a setting on the key, like its name and its cap: switch it off, and that key's requests leave nothing behind.
Send storage as false to PATCH /v1/keys/{hash}; the key's hash is in the list of your keys, GET /v1/keys.
The key routes take a management keyManagement keyThe key that runs your account through the API: the balance, the usage history, your keys, guardrails, observability. It never calls a model.More on API keys →, never an API key. An API key gets a 401. See API keys.
| The key's storage | Sent with a request | Got back | Uploaded to Files |
|---|---|---|---|
| on | kept | kept | kept |
| off | not kept | not kept | kept |
A key with storage off gets no file_id in its answers.
Do switch storage off on a key whose files you keep on your own side. Nothing else about the key changes.
The Storage page
Storage, in your Home, lists every file your account holds, from the API and from the chat, with the total size. From says where each came from: Chat, or API and the key's name. Download or delete any file there. Nothing on the page is charged.
A file from the chat never appears in the API's Files. It is listed on the Storage page and in its conversation.
Every route
All free, with your API key.
| Route | Does |
|---|---|
POST /v1/files | uploads a file |
GET /v1/files | lists your files |
GET /v1/files/{id} | one file's details |
GET /v1/files/{id}/content | the file's bytes |
DELETE /v1/files/{id} | deletes the file |
Errors
The body says why.
| Status | When |
|---|---|
| 400 | the request is malformed |
| 401 | the key is missing, wrong, disabled or expired |
| 404 | the file does not exist |
| 413 | the file is too large |
What to do on each: Errors and retries.
Last modified on