Files & Batches

File Operations

Upload, retrieve, list, and delete files. Files are used with batch processing, fine-tuning, and assistants.

Upload a File

Python

import asyncio
import base64
import json
import os
from pathlib import Path

from liter_llm import create_client
from liter_llm._internal_bindings import CreateFileRequest


async def main() -> None:
    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
    encoded = base64.b64encode(Path("data.jsonl").read_bytes()).decode("ascii")
    payload = {"file": encoded, "filename": "data.jsonl", "purpose": "batch"}
    request = CreateFileRequest.from_json(json.dumps(payload))
    response = await client.create_file(request)
    print(f"File ID: {response.id}")
    print(f"Size: {response.bytes} bytes")


asyncio.run(main())

TypeScript

import { createClient } from "@xberg-io/liter-llm";
import { readFileSync } from "node:fs";

const client = createClient(process.env.OPENAI_API_KEY!);
// file is a base64-encoded string, not raw bytes.
const file = readFileSync("data.jsonl").toString("base64");
const response = await client.createFile({
  file,
  filename: "data.jsonl",
  purpose: "batch",
});
console.log(`File ID: ${response.id}`);
console.log(`Size: ${response.bytes} bytes`);

Rust

use base64::Engine;
use liter_llm::{ClientConfigBuilder, CreateFileRequest, DefaultClient, FileClient, FilePurpose};
use tokio::fs;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfigBuilder::new(std::env::var("OPENAI_API_KEY")?)
        .build();
    let client = DefaultClient::new(config, Some("openai/gpt-4o"))?;

    let bytes = fs::read("data.jsonl").await?;
    let response = client
        .create_file(CreateFileRequest {
            file: base64::engine::general_purpose::STANDARD.encode(&bytes),
            filename: Some("data.jsonl".into()),
            purpose: FilePurpose::Batch,
        })
        .await?;

    println!("File ID: {}", response.id);
    println!("Size: {} bytes", response.bytes);
    Ok(())
}

Go

package main

import (
  "encoding/base64"
  "encoding/json"
  "fmt"
  "os"

  llm "github.com/xberg-io/liter-llm/packages/go"
)

func main() {
  client, err := llm.CreateClient(os.Getenv("OPENAI_API_KEY"), nil, nil, nil, nil)
  if err != nil {
    panic(err)
  }

  data, err := os.ReadFile("data.jsonl")
  if err != nil {
    panic(err)
  }

  body, _ := json.Marshal(map[string]string{
    "file":     base64.StdEncoding.EncodeToString(data),
    "filename": "data.jsonl",
    "purpose":  "batch",
  })

  var req llm.CreateFileRequest
  if err := json.Unmarshal(body, &req); err != nil {
    panic(err)
  }

  resp, err := client.CreateFile(req)
  if err != nil {
    panic(err)
  }
  fmt.Printf("File ID: %s\n", resp.ID)
  fmt.Printf("Size: %d bytes\n", resp.Bytes)
}

Java

import io.xberg.literllm.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;
import java.util.Optional;

public class Main {
    public static void main(String[] args) throws Exception {
        try (var client = LiterLlm.createClient(System.getenv("OPENAI_API_KEY"))) {
            byte[] fileBytes = Files.readAllBytes(Path.of("data.jsonl"));
            String fileBase64 = Base64.getEncoder().encodeToString(fileBytes);
            var response = client.createFile(CreateFileRequest.builder()
                .withFile(fileBase64)
                .withPurpose(FilePurpose.Batch)
                .withFilename(Optional.of("data.jsonl"))
                .build());
            System.out.println("File ID: " + response.id());
            System.out.println("Size: " + response.bytes() + " bytes");
        }
    }
}

C#

using LiterLlm;

using var client = LiterLlmLib.CreateClient(
    apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!,
    baseUrl: null, timeoutSecs: null, maxRetries: null, modelHint: null);

var fileBytes = await File.ReadAllBytesAsync("data.jsonl");
var response = await client.CreateFile(new CreateFileRequest
{
    File = Convert.ToBase64String(fileBytes),
    Filename = "data.jsonl",
    Purpose = FilePurpose.Batch
});
Console.WriteLine($"File ID: {response.Id}");
Console.WriteLine($"Size: {response.Bytes} bytes");

Ruby

# frozen_string_literal: true

require 'base64'
require 'liter_llm'

client = LiterLlm.create_client(ENV.fetch('OPENAI_API_KEY'))

result = client.create_file_async(
  LiterLlm::CreateFileRequest.new(
    file: Base64.strict_encode64(File.binread('data.jsonl')),
    filename: 'data.jsonl',
    purpose: 'batch'
  )
)

puts "File ID: #{result.id}"
puts "Size: #{result.bytes} bytes"

PHP

<?php

declare(strict_types=1);

use Liter\Llm\LiterLlm;
use Liter\Llm\CreateFileRequest;

$client = LiterLlm::createClient(getenv('OPENAI_API_KEY') ?: '');

$result = $client->createFileAsync(new CreateFileRequest(
    file: base64_encode(file_get_contents('data.jsonl')),
    purpose: 'batch',
    filename: 'data.jsonl',
));

echo "File ID: {$result->id}" . PHP_EOL;
echo "Size: {$result->bytes} bytes" . PHP_EOL;

Elixir

{:ok, client} = LiterLlm.create_client(System.get_env("OPENAI_API_KEY"))

request =
  Jason.encode!(%{
    file: Base.encode64(File.read!("data.jsonl")),
    filename: "data.jsonl",
    purpose: "batch"
  })

{:ok, result} = LiterLlm.defaultclient_create_file_async(client, request)
IO.puts("File ID: #{result.id}")
IO.puts("Size: #{result.bytes} bytes")

WASM

import init, {
  createClient,
  WasmCreateFileRequest,
  WasmFilePurpose,
} from "@xberg-io/liter-llm-wasm";

await init();

const client = createClient(process.env.OPENAI_API_KEY!);

// `file` is a base64-encoded string, not raw bytes.
const fileBytes = new Uint8Array(/* read from your storage */);
const fileBase64 = btoa(String.fromCharCode(...fileBytes));

const request = WasmCreateFileRequest.default();
request.file = fileBase64;
request.filename = "data.jsonl";
request.purpose = WasmFilePurpose.Batch;

const response = await client.createFile(request);
console.log(`File ID: ${response.id}`);
console.log(`Size: ${response.bytes} bytes`);

File Methods

Method	Description
create_file	Upload a file with a purpose ("batch", "fine-tune", "assistants")
retrieve_file	Get metadata for an uploaded file by ID
delete_file	Delete an uploaded file by ID
list_files	List all uploaded files, optionally filtered by purpose
file_content	Download the raw content of an uploaded file

Batch Processing

Create batch jobs to process multiple requests asynchronously at reduced cost:

Python

import asyncio
import os

from liter_llm import create_client
from liter_llm._internal_bindings import CreateBatchRequest


async def main() -> None:
    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
    request = CreateBatchRequest.from_json(
        '{"input_file_id":"file-abc123","endpoint":"/v1/chat/completions","completion_window":"24h"}'
    )
    response = await client.create_batch(request)
    print(f"Batch ID: {response.id}")
    print(f"Status: {response.status}")


asyncio.run(main())

TypeScript

import { createClient } from "@xberg-io/liter-llm";

const client = createClient(process.env.OPENAI_API_KEY!);
const response = await client.createBatch({
  inputFileId: "file-abc123",
  endpoint: "/v1/chat/completions",
  completionWindow: "24h",
});
console.log(`Batch ID: ${response.id}`);
console.log(`Status: ${response.status}`);

Rust

use liter_llm::{ClientConfigBuilder, CreateBatchRequest, DefaultClient, LlmClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfigBuilder::new(std::env::var("OPENAI_API_KEY")?)
        .build();
    let client = DefaultClient::new(config, Some("openai/gpt-4o"))?;

    let response = client
        .create_batch(CreateBatchRequest {
            input_file_id: "file-abc123".into(),
            endpoint: "/v1/chat/completions".into(),
            completion_window: "24h".into(),
            ..Default::default()
        })
        .await?;

    println!("Batch ID: {}", response.id);
    println!("Status: {}", response.status);
    Ok(())
}

Go

package main

import (
  "fmt"
  "os"

  llm "github.com/xberg-io/liter-llm/packages/go"
)

func main() {
  client, err := llm.CreateClient(os.Getenv("OPENAI_API_KEY"), nil, nil, nil, nil)
  if err != nil {
    panic(err)
  }

  req := llm.CreateBatchRequest{
    InputFileID:      "file-abc123",
    Endpoint:         "/v1/chat/completions",
    CompletionWindow: "24h",
  }

  resp, err := client.CreateBatch(req)
  if err != nil {
    panic(err)
  }
  fmt.Printf("Batch ID: %s\n", resp.ID)
  fmt.Printf("Status: %s\n", resp.Status)
}

Java

import io.xberg.literllm.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (var client = LiterLlm.createClient(System.getenv("OPENAI_API_KEY"))) {
            var response = client.createBatch(CreateBatchRequest.builder()
                .withInputFileId("file-abc123")
                .withEndpoint("/v1/chat/completions")
                .withCompletionWindow("24h")
                .build());
            System.out.println("Batch ID: " + response.id());
            System.out.println("Status: " + response.status());
        }
    }
}

C#

using LiterLlm;

using var client = LiterLlmLib.CreateClient(
    apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!,
    baseUrl: null, timeoutSecs: null, maxRetries: null, modelHint: null);

var response = await client.CreateBatch(new CreateBatchRequest
{
    InputFileId = "file-abc123",
    Endpoint = "/v1/chat/completions",
    CompletionWindow = "24h"
});
Console.WriteLine($"Batch ID: {response.Id}");
Console.WriteLine($"Status: {response.Status}");

Ruby

# frozen_string_literal: true

require 'liter_llm'

client = LiterLlm.create_client(ENV.fetch('OPENAI_API_KEY'))

result = client.create_batch_async(
  LiterLlm::CreateBatchRequest.new(
    input_file_id: 'file-abc123',
    endpoint: '/v1/chat/completions',
    completion_window: '24h'
  )
)

puts "Batch ID: #{result.id}"
puts "Status: #{result.status}"

PHP

<?php

declare(strict_types=1);

use Liter\Llm\LiterLlm;
use Liter\Llm\CreateBatchRequest;

$client = LiterLlm::createClient(getenv('OPENAI_API_KEY') ?: '');

$result = $client->createBatchAsync(new CreateBatchRequest(
    inputFileId: 'file-abc123',
    endpoint: '/v1/chat/completions',
    completionWindow: '24h',
));

echo "Batch ID: {$result->id}" . PHP_EOL;
echo "Status: {$result->status}" . PHP_EOL;

Elixir

{:ok, client} = LiterLlm.create_client(System.get_env("OPENAI_API_KEY"))

request =
  Jason.encode!(%{
    input_file_id: "file-abc123",
    endpoint: "/v1/chat/completions",
    completion_window: "24h"
  })

{:ok, result} = LiterLlm.defaultclient_create_batch_async(client, request)
IO.puts("Batch ID: #{result.id}")
IO.puts("Status: #{result.status}")

WASM

import init, { createClient, WasmCreateBatchRequest } from "@xberg-io/liter-llm-wasm";

await init();

const client = createClient(process.env.OPENAI_API_KEY!);

const request = WasmCreateBatchRequest.default();
request.inputFileId = "file-abc123";
request.endpoint = "/v1/chat/completions";
request.completionWindow = "24h";

const response = await client.createBatch(request);
console.log(`Batch ID: ${response.id}`);
console.log(`Status: ${response.status}`);

Batch Methods

Method	Description
create_batch	Create a batch from an uploaded JSONL file
retrieve_batch	Get batch status and results by ID
list_batches	List all batches
cancel_batch	Cancel a running batch

Batch Parameters

Parameter	Type	Description
input_file_id	string	ID of the uploaded JSONL file
endpoint	string	API endpoint ("/v1/chat/completions", "/v1/embeddings")
completion_window	string	Processing window ("24h")
metadata	object	Optional key-value metadata

Responses API

Create, retrieve, and cancel responses via the Responses API:

Python

import asyncio
import os

from liter_llm import create_client
from liter_llm._internal_bindings import CreateResponseRequest


async def main() -> None:
    client = create_client(api_key=os.environ["OPENAI_API_KEY"])
    request = CreateResponseRequest.from_json(
        '{"model":"openai/gpt-4o","input":"Explain quantum computing in one sentence."}'
    )
    response = await client.create_response(request)
    print(f"Status: {response.status}")
    for item in response.output:
        print(item.content)


asyncio.run(main())

TypeScript

import { createClient } from "@xberg-io/liter-llm";

const client = createClient(process.env.OPENAI_API_KEY!);
const response = await client.createResponse({
  model: "openai/gpt-4o",
  input: "Explain quantum computing in one sentence.",
});
console.log(`Status: ${response.status}`);
for (const item of response.output ?? []) {
  console.log(item.content);
}

Rust

use liter_llm::{
    ClientConfigBuilder, CreateResponseRequest, DefaultClient, ResponseClient,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfigBuilder::new(std::env::var("OPENAI_API_KEY")?)
        .build();
    let client = DefaultClient::new(config, Some("openai/gpt-4o"))?;

    let request = CreateResponseRequest {
        model: "openai/gpt-4o".into(),
        input: Some("Explain quantum computing in one sentence.".into()),
        ..Default::default()
    };

    let response = client.create_response(request).await?;
    println!("{:?}", response);
    Ok(())
}

Go

package main

import (
  "encoding/json"
  "fmt"
  "os"

  llm "github.com/xberg-io/liter-llm/packages/go"
)

func main() {
  client, err := llm.CreateClient(os.Getenv("OPENAI_API_KEY"), nil, nil, nil, nil)
  if err != nil {
    panic(err)
  }

  req := llm.CreateResponseRequest{
    Model: "openai/gpt-4o",
    Input: json.RawMessage(`"Explain quantum computing in one sentence."`),
  }

  resp, err := client.CreateResponse(req)
  if err != nil {
    panic(err)
  }
  fmt.Printf("Response ID: %s\n", resp.ID)
  fmt.Printf("Status: %s\n", resp.Status)
  for _, item := range resp.Output {
    fmt.Println(string(item.Content))
  }
}

Java

import io.xberg.literllm.*;

public class Main {
    public static void main(String[] args) throws Exception {
        try (var client = LiterLlm.createClient(System.getenv("OPENAI_API_KEY"))) {
            var response = client.createResponse(CreateResponseRequest.builder()
                .withModel("openai/gpt-4o")
                .withInput("Explain quantum computing in one sentence.")
                .build());
            System.out.println(response);
        }
    }
}

C#

using LiterLlm;

using var client = LiterLlmLib.CreateClient(
    apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!,
    baseUrl: null, timeoutSecs: null, maxRetries: null, modelHint: null);

var response = await client.CreateResponse(new CreateResponseRequest
{
    Model = "openai/gpt-4o",
    Input = "Explain quantum computing in one sentence."
});
Console.WriteLine(response);

Ruby

# frozen_string_literal: true

require 'liter_llm'

client = LiterLlm.create_client(ENV.fetch('OPENAI_API_KEY'))

result = client.create_response_async(
  LiterLlm::CreateResponseRequest.new(
    model: 'openai/gpt-4o',
    input: 'Explain quantum computing in one sentence.'
  )
)

puts "Response ID: #{result.id}"
puts "Status: #{result.status}"
result.output.each { |item| puts item.content }

PHP

<?php

declare(strict_types=1);

use Liter\Llm\LiterLlm;
use Liter\Llm\CreateResponseRequest;

$client = LiterLlm::createClient(getenv('OPENAI_API_KEY') ?: '');

$request = CreateResponseRequest::from_json(json_encode([
    'model' => 'openai/gpt-4o',
    'input' => 'Explain quantum computing in one sentence.',
]));

$result = $client->createResponseAsync($request);
echo "Response ID: {$result->id}" . PHP_EOL;
echo "Status: {$result->status}" . PHP_EOL;
foreach ($result->output as $item) {
    echo $item->content . PHP_EOL;
}

Elixir

{:ok, client} = LiterLlm.create_client(System.get_env("OPENAI_API_KEY"))

request =
  Jason.encode!(%{
    model: "openai/gpt-4o",
    input: "Explain quantum computing in one sentence."
  })

{:ok, result} = LiterLlm.defaultclient_create_response_async(client, request)
IO.puts("Response ID: #{result.id}")
IO.puts("Status: #{result.status}")

for item <- result.output, do: IO.puts(item.content)

WASM

import init, { createClient, WasmCreateResponseRequest } from "@xberg-io/liter-llm-wasm";

await init();

const client = createClient(process.env.OPENAI_API_KEY!);

const request = WasmCreateResponseRequest.default();
request.model = "openai/gpt-4o";
request.input = "Explain quantum computing in one sentence.";

const response = await client.createResponse(request);
console.log(`Status: ${response.status}`);
for (const item of response.output ?? []) {
  console.log(item.content);
}

Response Methods

Method	Description
create_response	Create a new response
retrieve_response	Get a response by ID
cancel_response	Cancel a response

Response Parameters

Parameter	Type	Description
model	string	Model to use
input	string	Input text or conversation
instructions	string	System-level instructions
max_output_tokens	int	Maximum tokens to generate
temperature	float	Sampling temperature