CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-langfuse--langfuse-java

Java client for the Langfuse API providing access to observability and analytics features for LLM applications

Overview
Eval results
Files

models.mddocs/

Models

The Models API provides management of LLM model definitions and pricing configurations. Models define token costs and usage tracking for different LLM providers and versions.

Capabilities

ModelsClient

Client for managing LLM model definitions.

/**
 * Create a model definition
 *
 * @param request Model configuration with pricing
 * @param requestOptions Optional request configuration
 */
Model create(CreateModelRequest request);
Model create(CreateModelRequest request, RequestOptions requestOptions);

/**
 * List all models
 *
 * @param request Optional pagination parameters
 * @param requestOptions Optional request configuration
 */
PaginatedModels list();
PaginatedModels list(GetModelsRequest request);
PaginatedModels list(GetModelsRequest request, RequestOptions requestOptions);

/**
 * Get a model by ID
 *
 * @param id Model ID
 * @param requestOptions Optional request configuration
 */
Model get(String id);
Model get(String id, RequestOptions requestOptions);

/**
 * Delete a model
 * Note: Cannot delete Langfuse-managed models
 *
 * @param id Model ID
 * @param requestOptions Optional request configuration
 */
void delete(String id);
void delete(String id, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.models.types.*;
import com.langfuse.client.resources.models.requests.*;
import com.langfuse.client.resources.commons.types.*;
import java.time.OffsetDateTime;

LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// Create a custom model
CreateModelRequest modelRequest = CreateModelRequest.builder()
    .modelName("gpt-4-custom")
    .matchPattern("gpt-4-custom.*")
    .unit(ModelUsageUnit.TOKENS)
    .inputPrice(0.03)   // $0.03 per 1000 tokens
    .outputPrice(0.06)  // $0.06 per 1000 tokens
    .startDate(OffsetDateTime.parse("2025-10-01T00:00:00Z"))
    .build();

Model model = client.models().create(modelRequest);
System.out.println("Created model: " + model.getId());

// List all models
PaginatedModels models = client.models().list();
for (Model m : models.getData()) {
    System.out.println(m.getModelName() + " - " + m.getUnit());
}

// Get a specific model
Model retrieved = client.models().get(model.getId());

// Delete a custom model
client.models().delete(model.getId());

Request Types

CreateModelRequest

/**
 * Request for creating a model
 */
public final class CreateModelRequest {
    String getModelName();                       // Model name
    String getMatchPattern();                    // Regex pattern for matching
    Optional<OffsetDateTime> getStartDate();     // ISO 8601 timestamp
    Optional<Double> getInputPrice();            // Price per unit for input
    Optional<Double> getOutputPrice();           // Price per unit for output
    Optional<Double> getTotalPrice();            // Price per unit (if not split)
    Optional<ModelUsageUnit> getUnit();          // TOKENS, CHARACTERS, REQUESTS, etc.
    Optional<String> getTokenizerId();           // Tokenizer identifier
    Optional<Object> getTokenizerConfig();       // Tokenizer configuration

    static Builder builder();
}

GetModelsRequest

/**
 * Request parameters for listing models
 */
public final class GetModelsRequest {
    Optional<Integer> getPage();   // Page number (default: 1)
    Optional<Integer> getLimit();  // Items per page (default: 50)

    static Builder builder();
}

Response Types

Model

/**
 * LLM model definition with pricing
 */
public final class Model {
    String getId();
    String getModelName();
    String getMatchPattern();
    Optional<OffsetDateTime> getStartDate();      // ISO 8601 timestamp
    Optional<ModelUsageUnit> getUnit();           // TOKENS, CHARACTERS, etc.
    Optional<Double> getInputPrice();             // Deprecated: Input price (USD)
    Optional<Double> getOutputPrice();            // Deprecated: Output price (USD)
    Optional<Double> getTotalPrice();             // Deprecated: Total price (USD)
    Optional<String> getTokenizerId();            // Tokenizer identifier
    Optional<Object> getTokenizerConfig();        // Tokenizer configuration
    boolean getIsLangfuseManaged();               // True for built-in models
    Map<String, ModelPrice> getPrices();          // Price by usage type

    static Builder builder();
}

ModelPrice

/**
 * Pricing information for a model
 */
public final class ModelPrice {
    double getPrice();       // Price per unit (in USD)

    static Builder builder();
}

PaginatedModels

/**
 * Paginated list of models
 */
public final class PaginatedModels {
    List<Model> getData();
    MetaResponse getMeta();  // Pagination metadata

    static Builder builder();
}

Enums

ModelUsageUnit

/**
 * Unit for usage measurement
 */
public enum ModelUsageUnit {
    CHARACTERS,  // Character-based pricing
    TOKENS,      // Token-based pricing
    REQUESTS,    // Request-based pricing
    IMAGES,      // Image-based pricing
    SECONDS      // Time-based pricing
}

Complete Model Management Example

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.models.types.*;
import com.langfuse.client.resources.models.requests.*;
import com.langfuse.client.resources.commons.types.*;
import java.time.OffsetDateTime;

public class ModelManagementExample {
    public static void main(String[] args) {
        LangfuseClient client = LangfuseClient.builder()
            .url("https://cloud.langfuse.com")
            .credentials("pk-lf-...", "sk-lf-...")
            .build();

        // 1. Create a custom GPT-4 model variant
        CreateModelRequest gpt4Custom = CreateModelRequest.builder()
            .modelName("gpt-4-turbo-custom")
            .matchPattern("gpt-4-turbo-custom.*")
            .unit(ModelUsageUnit.TOKENS)
            .inputPrice(0.01)
            .outputPrice(0.03)
            .startDate(OffsetDateTime.parse("2025-10-01T00:00:00Z"))
            .build();

        Model gpt4Model = client.models().create(gpt4Custom);
        System.out.println("Created GPT-4 custom model: " + gpt4Model.getId());

        // 2. Create a Claude model
        CreateModelRequest claudeModel = CreateModelRequest.builder()
            .modelName("claude-3-sonnet")
            .matchPattern("claude-3-sonnet.*")
            .unit(ModelUsageUnit.TOKENS)
            .inputPrice(0.003)
            .outputPrice(0.015)
            .build();

        client.models().create(claudeModel);

        // 3. Create an image model
        CreateModelRequest dalleModel = CreateModelRequest.builder()
            .modelName("dall-e-3")
            .matchPattern("dall-e-3")
            .unit(ModelUsageUnit.IMAGES)
            .totalPrice(0.040)  // $0.04 per image (1024x1024)
            .build();

        client.models().create(dalleModel);

        // 4. List all models
        System.out.println("\nAll models:");
        PaginatedModels models = client.models().list();
        for (Model model : models.getData()) {
            System.out.println("  " + model.getModelName());
            if (model.getUnit().isPresent()) {
                System.out.println("    Unit: " + model.getUnit().get());
            }

            // Check deprecated price fields
            if (model.getInputPrice().isPresent()) {
                System.out.println("    Input: $" + model.getInputPrice().get() +
                                 " per " + model.getUnit().orElse(ModelUsageUnit.TOKENS));
            }
            if (model.getOutputPrice().isPresent()) {
                System.out.println("    Output: $" + model.getOutputPrice().get() +
                                 " per " + model.getUnit().orElse(ModelUsageUnit.TOKENS));
            }
            if (model.getTotalPrice().isPresent()) {
                System.out.println("    Total: $" + model.getTotalPrice().get() +
                                 " per " + model.getUnit().orElse(ModelUsageUnit.TOKENS));
            }

            // Check new prices map
            if (!model.getPrices().isEmpty()) {
                System.out.println("    Prices:");
                model.getPrices().forEach((usageType, price) ->
                    System.out.println("      " + usageType + ": $" + price.getPrice())
                );
            }
        }

        // 5. Get a specific model
        Model retrieved = client.models().get(gpt4Model.getId());
        System.out.println("\nRetrieved model: " + retrieved.getModelName());
        System.out.println("Match pattern: " + retrieved.getMatchPattern());

        // 6. Update model (create new version with different date)
        CreateModelRequest gpt4Updated = CreateModelRequest.builder()
            .modelName("gpt-4-turbo-custom")
            .matchPattern("gpt-4-turbo-custom.*")
            .unit(ModelUsageUnit.TOKENS)
            .inputPrice(0.008)  // New pricing
            .outputPrice(0.025)
            .startDate(OffsetDateTime.parse("2025-11-01T00:00:00Z"))  // New start date
            .build();

        client.models().create(gpt4Updated);

        // 7. Clean up - delete custom models
        // Note: Cannot delete Langfuse-managed models
        try {
            client.models().delete(gpt4Model.getId());
            System.out.println("\nDeleted custom model");
        } catch (Exception e) {
            System.err.println("Cannot delete: " + e.getMessage());
        }
    }
}

Best Practices

  1. Match Patterns: Use regex patterns to match model variants (e.g., gpt-4.*)
  2. Versioned Pricing: Create new model entries with different start dates for pricing changes
  3. Unit Consistency: Use consistent units across model variants
  4. Custom Models: Create custom models for fine-tuned or self-hosted models
  5. Documentation: Store tokenizer config for reproducibility
  6. Scale-to-Zero: Use isScaleToZero flag for serverless deployments
  7. Currency: Default currency is USD, specify in ModelPrice if different

Pricing Calculation

Models are used to automatically calculate costs for observations:

// When creating an observation with usage info
CreateGenerationEvent generation = CreateGenerationEvent.builder()
    .body(CreateGenerationBody.builder()
        .id("gen-123")
        .traceId("trace-123")
        .model("gpt-4-turbo-custom")  // Matches model definition
        .usage(IngestionUsage.usageDetails(
            UsageDetails.builder()
                .input(500)   // 500 tokens
                .output(200)  // 200 tokens
                .unit(ModelUsageUnit.TOKENS)
                .build()
        ))
        .build())
    .build();

// Langfuse automatically calculates:
// cost = (500 * 0.01 / 1000) + (200 * 0.03 / 1000) = $0.005 + $0.006 = $0.011

Related Documentation

  • Traces and Observations - Using models in observations
  • Ingestion API - Creating observations with model info
  • Common Types - Model type definitions
  • Pagination - Pagination utilities

Install with Tessl CLI

npx tessl i tessl/maven-com-langfuse--langfuse-java

docs

client-configuration.md

comments-annotations.md

common-types.md

datasets.md

exceptions.md

health.md

index.md

ingestion.md

media.md

metrics.md

models.md

pagination.md

projects-organizations.md

prompts.md

scim.md

scores.md

sessions.md

traces-observations.md

tile.json