opendunes
Your account · 4 min
Copy page ▾

Files and storage

What is kept of a model's output, and for how long: every file, until you delete it.

  1. Upload a file.
  2. Use it in a request.
  3. Find what a model made.
  4. Delete a file.
What is keptevery file a key sends or gets back: pictures, clips, songs, speech, uploads
How longuntil you delete it: a kept file never expires
As whatbyte for byte, as it arrived: never resized or re-encoded
What it costsnothing, 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"])
FieldHolds
idthe file's ID, such as 3f6c2a9e-8b1d-4e7a-9c5f-2d4b6a8e1c07
filenamethe name it was sent with
mime_typewhat the file is, read from its bytes
size_bytesits size
created_atwhen it was kept
downloadabletrue 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:

JSON
{
  "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 answerCarries the ID
a picture, a song or a spoken reply inside the answerfile_id, beside each file, one per file, in order
the file itself as raw bytes, such as speechthe header X-File-Id

A picture, as it comes back, illustrative:

JSON
{
  "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.

Good to know

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.

Watch out

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 deleteGoes
a file, from Files or the Storage pagethat file
a conversation in the chatevery file in it
your accountevery 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.

Watch out

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 storageSent with a requestGot backUploaded to Files
onkeptkeptkept
offnot keptnot keptkept

A key with storage off gets no file_id in its answers.

Do

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.

Watch out

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.

RouteDoes
POST /v1/filesuploads a file
GET /v1/fileslists your files
GET /v1/files/{id}one file's details
GET /v1/files/{id}/contentthe file's bytes
DELETE /v1/files/{id}deletes the file

Errors

The body says why.

StatusWhen
400the request is malformed
401the key is missing, wrong, disabled or expired
404the file does not exist
413the file is too large

What to do on each: Errors and retries.

Last modified on