Upload and reference files

Upload a file once and reference its InOneAPI file_id in model requests. After checking ownership, the gateway converts it to a private COS signed URL or inline content for the selected upstream protocol, then applies the mapping DSL. Provider capability is not prevalidated; unsupported inputs are reported by the upstream.

Endpoints and access

Send Authorization: Bearer $INONEAPI_API_KEY. Files belong exclusively to the uploading API key. Other keys, including keys in the same project or owned by the same user, cannot access them. These IDs are not upstream file IDs or Playground attachment IDs.

File operations do not incur model inference charges or require a positive wallet balance. Key rate/concurrency limits and project status still apply. Fine-tuning, Batch, vector search and upstream Files API passthrough are not provided.

Upload

Required multipart fields: file contains the bytes; purpose must be user_data. Let your HTTP client set the multipart boundary.

curl https://api.inoneapi.com/v1/files \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -F purpose=user_data \
  -F file=@./sample.mp4

{
  "id": "file_ioa_0123456789abcdef0123456789abcdef",
  "object": "file",
  "filename": "sample.mp4",
  "mime_type": "video/mp4",
  "media_type": "video",
  "bytes": 1048576,
  "status": "ready",
  "created_at": 1789430400,
  "purpose": "user_data"
}

Maximum: 10 MiB per image, audio or document; 32 MiB per video. Each key allows 1 GiB and 1000 file records created in the last 24 hours, including pending uploads. MIME and media type are detected from content. Accepted formats: PNG/JPEG/WebP/GIF, MP4/WebM/MOV, MP3/WAV/OGG/AAC/FLAC/M4A, PDF, plain text, CSV and JSON. Container and text subtypes follow the detected metadata. No transcoding, OCR, document parsing or thumbnails are performed.

A model request may contain up to 32 file references with at most 64 MiB of source data, counting repeated references separately. The expanded JSON must also fit the gateway request-body limit. Upload acceptance does not guarantee provider support.

Chat Completions

Mix text and file references in the same message:

{
  "model": "YOUR_MODEL_ID",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe this video"},
      {"type": "file", "file": {"file_id": "file_ioa_0123456789abcdef0123456789abcdef"}}
    ]
  }]
}

Using type: file for all media and the video_url content type are InOneAPI extensions, not the OpenAI standard video protocol. Existing text and URLs retain their order and content.

Responses and Messages

Responses uses {"type":"input_file","file_id":"..."} inside input[].content. Documents become input_file.file_url; images become input_image.image_url. An explicit {"type":"input_image","file_id":"..."} requires an image.

Video/audio references through input_file are extensions: video becomes {"type":"input_video","video_url":"COS signed URL"}; audio uses the input_audio block shown above.

Messages uses {"type":"document","source":{"type":"file","file_id":"..."}} inside messages[].content. The block type must match document, image, audio or video. PDFs and images become URL sources. Plain text, CSV and JSON become a source with type: text, media_type: text/plain, and data containing the text. Audio/video blocks are InOneAPI extensions using URL sources. /v1/messages/count_tokens follows the same rules.

If Responses or Messages routes to a Chat upstream, files expand directly to Chat content before the outer request protocol is converted. Platform IDs never pass through as upstream file IDs.

Video, image and speech generation

Media source.type also accepts file_id as an alias of file; both require an InOneAPI file ID.

POST /v1/videos, POST /v1/images/generations and POST /v1/audio/speech accept this reference fragment:

{
  "input_references": [{
    "type": "image",
    "role": "first_frame",
    "source": {"type": "file", "file_id": "file_ioa_0123456789abcdef0123456789abcdef"}
  }]
}

Merge it into the original request; required fields such as model, prompt, or speech input and voice remain required. Reference type must match the file's image/audio/video type. Only source is replaced by {"type":"url","url":"COS signed URL"}; role is preserved for the mapping DSL. For Images and Speech, input_references is an InOneAPI extension, not an OpenAI parameter. This feature does not add image editing, transcription or translation endpoints.

Pagination, deletion and retention

Lists return object: list, data, has_more, first_id and last_id. Pass last_id as the next after cursor. The cursor must belong to the same key.

curl https://api.inoneapi.com/v1/files \
  -H "Authorization: Bearer $INONEAPI_API_KEY"

curl -X DELETE https://api.inoneapi.com/v1/files/file_ioa_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $INONEAPI_API_KEY"

Deletion returns {"id":"file_ioa_...","object":"file","deleted":true}. Public API files are retained for one day by COS lifecycle. The application does not set or return an independent expires_at or run a cleanup worker. COS deletion is asynchronous, not precisely 24 hours after upload. Signed URLs last five minutes and are regenerated per upstream attempt; URL authorization does not set object retention. Asynchronous providers must retrieve content while both the URL and object are available.

Content is stored in private COS; the database stores only object keys and metadata. File uploads are outside inference zero-data mode. Configure a one-day COS lifecycle rule for only api-files/, never playground/: Playground attachments have no lifecycle expiration. Deleting an API key invalidates its IDs; COS cleans up remaining objects. COS deletion does not remove database metadata: ready means the upload completed, not that the object still exists. Upload again after object deletion. Old metadata does not consume the rolling 24-hour quota and can be removed through DELETE.

Interrupted uploads may leave uploading records. Find their IDs in the list and delete them after five minutes. Only ready files may be referenced. Deletion cannot recall content already sent upstream.

Errors

Existing authentication, key rate limits, routing and upstream errors still apply.