Transform Any File
Upload a single file to Roset and get back every structured representation your app needs: markdown, embeddings, metadata, and a searchable index. This is the core workflow -- one API call triggers the full transformation pipeline.
The Workflow
Your File --> Roset --> Route to Provider --> Extract --> Embed --> 4 Variants
- Upload your file (PDF, image, audio, or document)
- Roset routes it to the right extraction provider (Reducto, Gemini, or Whisper)
- Extraction produces markdown and metadata
- Embedding generates vector embeddings via OpenAI
- You retrieve any or all of the 4 variant types
Complete Example
python
import os
import time
from roset import Client
client = Client(api_key=os.getenv("ROSET_API_KEY"))
# 1. Upload a file
file = client.files.upload(
filename="quarterly-report.pdf",
content_type="application/pdf",
size_bytes=128000,
)
print(f"File {file['id']} uploaded, job: {file['job_id']}")
# 2. Wait for transformation to complete
while True:
current = client.files.get(file["id"])
status = current["status"]
print(f"Status: {status}")
if status in ("completed", "failed"):
break
time.sleep(2)
if status == "failed":
print("Transformation failed")
exit(1)
# 3. Retrieve all variants
result = client.files.list_variants(file["id"])
for v in result["variants"]:
print(f" {v['type']}: {v['size_bytes']} bytes")
# 4. Get specific variants
markdown = client.files.get_variant(file["id"], "markdown")
print(markdown["content"][:500])
metadata = client.files.get_variant(file["id"], "metadata")
print(f"Pages: {metadata.get('pageCount')}, Language: {metadata.get('language')}")What Gets Produced
Every file transformation produces up to 4 variant types. See Variant Types for details on each.
| Variant | What it contains | Provider |
|---|---|---|
markdown | Extracted text in markdown format | Reducto, Gemini, or Whisper |
embeddings | Vector embeddings for each chunk | OpenAI |
metadata | Page count, language, extraction confidence | Extraction provider |
searchable-index | Full-text search index | Roset |
Provider Routing
Roset automatically selects the right extraction provider based on content type:
| Content Type | Provider | File Types |
|---|---|---|
| Documents | Reducto | PDF, DOCX, PPTX, XLSX |
| Images | Gemini | PNG, JPG, TIFF, WEBP |
| Audio | Whisper | MP3, WAV, M4A, OGG |
You can override the provider per-upload:
python
# Force Gemini for a specific PDF (e.g., scanned images)
file = client.files.upload(
filename="scanned-doc.pdf",
content_type="application/pdf",
size_bytes=500000,
provider="gemini",
)Selective Variants
By default, Roset generates all applicable variants. You can request only specific types:
python
# Only generate markdown and embeddings (skip metadata, index)
file = client.files.upload(
filename="notes.pdf",
content_type="application/pdf",
size_bytes=12000,
variants=["markdown", "embeddings"],
)Batch Uploads
Process many files at once with batch upload:
python
# Upload multiple files in one call
batch = client.files.upload_batch([
{"filename": "report-q1.pdf", "content_type": "application/pdf", "size_bytes": 45678},
{"filename": "report-q2.pdf", "content_type": "application/pdf", "size_bytes": 56789},
{"filename": "photo.jpg", "content_type": "image/jpeg", "size_bytes": 234567},
])
for f in batch["files"]:
print(f" {f['filename']}: {f['id']}")Note
For production workloads, use webhooks instead of polling. Roset will POST to your endpoint when each file's transformation completes.
Build this with AI
Roset (roset.dev) is a developer API that transforms unstructured files into structured data. You upload a file and get back variants: markdown, embeddings, metadata, searchable index. Python SDK: `pip install roset`. Init: `from roset import Client; client = Client(api_key='rsk_...')`. Upload: `client.files.upload(filename='doc.pdf', content_type='application/pdf', size_bytes=N)`. Poll: `client.files.get(file_id)` until status is 'completed'. Retrieve: `client.files.list_variants(file_id)`. Write me a complete Python script that uploads a PDF, waits for processing, and prints the markdown and embeddings variants.
Next Steps
- Build a Knowledge Base -- search across many transformed files with Q&A.
- Variant Types -- deep dive on what each variant contains.
- Webhooks -- get notified instead of polling.