Skip to main content

​
Overview

The Dedalus SDK provides flexible file upload support for endpoints like audio transcriptions and translations. You can upload files from multiple sources using the toFile helper or directly pass file objects.

​
Supported File Sources

Request parameters that accept file uploads support multiple formats:
  • File objects (or objects with the same structure)
  • fetch Response objects
  • fs.ReadStream (Node.js)
  • The return value of the toFile helper
  • Raw Blob or ArrayBuffer data

​
Using the toFile Helper

The toFile helper converts various data types into a File object that can be uploaded.

​
Import the Helper

import Dedalus, { toFile } from 'dedalus-labs';

​
Basic Usage

import fs from 'fs';
import Dedalus, { toFile } from 'dedalus-labs';

const client = new Dedalus();

// Method 1: Using fs.createReadStream (recommended for Node.js)
await client.audio.transcriptions.create({
  file: fs.createReadStream('/path/to/audio.mp3'),
  model: 'whisper-1',
});

// Method 2: Using toFile with Buffer
await client.audio.transcriptions.create({
  file: await toFile(Buffer.from('my audio bytes'), 'audio.mp3'),
  model: 'whisper-1',
});

// Method 3: Using toFile with fs.readFileSync
await client.audio.transcriptions.create({
  file: await toFile(fs.readFileSync('/path/to/audio.mp3'), 'audio.mp3'),
  model: 'whisper-1',
});

​
Using Web File API

If you have access to the web File API (browsers, modern runtimes), you can pass File instances directly: 
import Dedalus from 'dedalus-labs';

const client = new Dedalus();

// From a file input element (browser)
const fileInput = document.querySelector('input[type="file"]') as HTMLInputElement;
const file = fileInput.files?.[0];

if (file) {
  await client.audio.transcriptions.create({
    file: file,
    model: 'whisper-1',
  });
}

// Creating a File manually
const file = new File(['my audio bytes'], 'audio.mp3', { type: 'audio/mpeg' });
await client.audio.transcriptions.create({
  file: file,
  model: 'whisper-1',
});

​
Using fetch Response

You can pass a fetch Response object directly: 
import Dedalus from 'dedalus-labs';

const client = new Dedalus();

const response = await fetch('https://example.com/audio.mp3');

await client.audio.transcriptions.create({
  file: response,
  model: 'whisper-1',
});
When using a Response object, the SDK automatically extracts the filename from the URL if not provided.

​
toFile Options

The toFile helper accepts optional configuration: 
await toFile(
  value: ToFileInput | PromiseLike<ToFileInput>,
  name?: string | null | undefined,
  options?: {
    type?: string;         // MIME type
    lastModified?: number; // Last modified timestamp
  }
): Promise<File>

​
Specifying MIME Type

import { toFile } from 'dedalus-labs';

const file = await toFile(
  Buffer.from('audio data'),
  'recording.mp3',
  { type: 'audio/mpeg' }
);

​
Setting Last Modified

import { toFile } from 'dedalus-labs';

const file = await toFile(
  Buffer.from('audio data'),
  'recording.mp3',
  { 
    type: 'audio/mpeg',
    lastModified: Date.now()
  }
);

​
Working with Different Data Types

​
Uint8Array

import { toFile } from 'dedalus-labs';

const data = new Uint8Array([0, 1, 2, 3, 4]);
const file = await toFile(data, 'data.bin');

await client.audio.transcriptions.create({
  file: file,
  model: 'whisper-1',
});

​
ArrayBuffer

import { toFile } from 'dedalus-labs';

const buffer = new ArrayBuffer(1024);
const file = await toFile(buffer, 'audio.raw');

await client.audio.transcriptions.create({
  file: file,
  model: 'whisper-1',
});

​
Blob

import { toFile } from 'dedalus-labs';

const blob = new Blob(['audio data'], { type: 'audio/mpeg' });
const file = await toFile(blob, 'audio.mp3');

await client.audio.transcriptions.create({
  file: file,
  model: 'whisper-1',
});

​
Async Iterables

You can stream data from async iterables: 
import { toFile } from 'dedalus-labs';

async function* generateAudioChunks() {
  yield new Uint8Array([0, 1, 2]);
  yield new Uint8Array([3, 4, 5]);
  yield new Uint8Array([6, 7, 8]);
}

const file = await toFile(generateAudioChunks(), 'streamed-audio.mp3');

await client.audio.transcriptions.create({
  file: file,
  model: 'whisper-1',
});

​
Audio Transcription Example

Complete example with different runtimes: 
import fs from 'fs';
import Dedalus from 'dedalus-labs';

const client = new Dedalus();

const transcription = await client.audio.transcriptions.create({
  file: fs.createReadStream('./meeting-recording.mp3'),
  model: 'whisper-1',
  language: 'en',
  response_format: 'json',
});

console.log(transcription.text);

​
Error Handling

import Dedalus from 'dedalus-labs';
import fs from 'fs';

const client = new Dedalus();

try {
  const transcription = await client.audio.transcriptions.create({
    file: fs.createReadStream('./audio.mp3'),
    model: 'whisper-1',
  });
  console.log(transcription.text);
} catch (error) {
  if (error instanceof Dedalus.APIError) {
    console.error('API Error:', error.status, error.message);
  } else if (error.code === 'ENOENT') {
    console.error('File not found');
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Best Practices

1

Use streams for large files

For Node.js, prefer fs.createReadStream() over reading entire files into memory with fs.readFileSync().
2

Specify MIME types

Always specify the correct MIME type when using toFile to ensure proper handling.
3

Handle file not found errors

Add proper error handling for missing files and file system errors.
4

Close file handles

When using file streams, ensure they are properly closed after upload.
The SDK will throw an error if you attempt to use file uploads in environments that don’t support the File API. Always check toFile availability in your runtime.

Build docs developers (and LLMs) love

Get started for freeTalk to us