0
# Models
1

2
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.
3

4
## Capabilities
5

6
### ModelsClient
7

8
Client for managing LLM model definitions.
9

10
```java { .api }
11
/**
12
 * Create a model definition
13
 *
14
 * @param request Model configuration with pricing
15
 * @param requestOptions Optional request configuration
16
 */
17
Model create(CreateModelRequest request);
18
Model create(CreateModelRequest request, RequestOptions requestOptions);
19

20
/**
21
 * List all models
22
 *
23
 * @param request Optional pagination parameters
24
 * @param requestOptions Optional request configuration
25
 */
26
PaginatedModels list();
27
PaginatedModels list(GetModelsRequest request);
28
PaginatedModels list(GetModelsRequest request, RequestOptions requestOptions);
29

30
/**
31
 * Get a model by ID
32
 *
33
 * @param id Model ID
34
 * @param requestOptions Optional request configuration
35
 */
36
Model get(String id);
37
Model get(String id, RequestOptions requestOptions);
38

39
/**
40
 * Delete a model
41
 * Note: Cannot delete Langfuse-managed models
42
 *
43
 * @param id Model ID
44
 * @param requestOptions Optional request configuration
45
 */
46
void delete(String id);
47
void delete(String id, RequestOptions requestOptions);
48
```
49

50
**Usage Examples:**
51

52
```java
53
import com.langfuse.client.LangfuseClient;
54
import com.langfuse.client.resources.models.types.*;
55
import com.langfuse.client.resources.models.requests.*;
56
import com.langfuse.client.resources.commons.types.*;
57
import java.time.OffsetDateTime;
58

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

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

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

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

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

86
// Delete a custom model
87
client.models().delete(model.getId());
88
```
89

90
## Request Types
91

92
### CreateModelRequest
93

94
```java { .api }
95
/**
96
 * Request for creating a model
97
 */
98
public final class CreateModelRequest {
99
    String getModelName();                       // Model name
100
    String getMatchPattern();                    // Regex pattern for matching
101
    Optional<OffsetDateTime> getStartDate();     // ISO 8601 timestamp
102
    Optional<Double> getInputPrice();            // Price per unit for input
103
    Optional<Double> getOutputPrice();           // Price per unit for output
104
    Optional<Double> getTotalPrice();            // Price per unit (if not split)
105
    Optional<ModelUsageUnit> getUnit();          // TOKENS, CHARACTERS, REQUESTS, etc.
106
    Optional<String> getTokenizerId();           // Tokenizer identifier
107
    Optional<Object> getTokenizerConfig();       // Tokenizer configuration
108

109
    static Builder builder();
110
}
111
```
112

113
### GetModelsRequest
114

115
```java { .api }
116
/**
117
 * Request parameters for listing models
118
 */
119
public final class GetModelsRequest {
120
    Optional<Integer> getPage();   // Page number (default: 1)
121
    Optional<Integer> getLimit();  // Items per page (default: 50)
122

123
    static Builder builder();
124
}
125
```
126

127
## Response Types
128

129
### Model
130

131
```java { .api }
132
/**
133
 * LLM model definition with pricing
134
 */
135
public final class Model {
136
    String getId();
137
    String getModelName();
138
    String getMatchPattern();
139
    Optional<OffsetDateTime> getStartDate();      // ISO 8601 timestamp
140
    Optional<ModelUsageUnit> getUnit();           // TOKENS, CHARACTERS, etc.
141
    Optional<Double> getInputPrice();             // Deprecated: Input price (USD)
142
    Optional<Double> getOutputPrice();            // Deprecated: Output price (USD)
143
    Optional<Double> getTotalPrice();             // Deprecated: Total price (USD)
144
    Optional<String> getTokenizerId();            // Tokenizer identifier
145
    Optional<Object> getTokenizerConfig();        // Tokenizer configuration
146
    boolean getIsLangfuseManaged();               // True for built-in models
147
    Map<String, ModelPrice> getPrices();          // Price by usage type
148

149
    static Builder builder();
150
}
151
```
152

153
### ModelPrice
154

155
```java { .api }
156
/**
157
 * Pricing information for a model
158
 */
159
public final class ModelPrice {
160
    double getPrice();       // Price per unit (in USD)
161

162
    static Builder builder();
163
}
164
```
165

166
### PaginatedModels
167

168
```java { .api }
169
/**
170
 * Paginated list of models
171
 */
172
public final class PaginatedModels {
173
    List<Model> getData();
174
    MetaResponse getMeta();  // Pagination metadata
175

176
    static Builder builder();
177
}
178
```
179

180
## Enums
181

182
### ModelUsageUnit
183

184
```java { .api }
185
/**
186
 * Unit for usage measurement
187
 */
188
public enum ModelUsageUnit {
189
    CHARACTERS,  // Character-based pricing
190
    TOKENS,      // Token-based pricing
191
    REQUESTS,    // Request-based pricing
192
    IMAGES,      // Image-based pricing
193
    SECONDS      // Time-based pricing
194
}
195
```
196

197
## Complete Model Management Example
198

199
```java
200
import com.langfuse.client.LangfuseClient;
201
import com.langfuse.client.resources.models.types.*;
202
import com.langfuse.client.resources.models.requests.*;
203
import com.langfuse.client.resources.commons.types.*;
204
import java.time.OffsetDateTime;
205

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

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

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

226
        // 2. Create a Claude model
227
        CreateModelRequest claudeModel = CreateModelRequest.builder()
228
            .modelName("claude-3-sonnet")
229
            .matchPattern("claude-3-sonnet.*")
230
            .unit(ModelUsageUnit.TOKENS)
231
            .inputPrice(0.003)
232
            .outputPrice(0.015)
233
            .build();
234

235
        client.models().create(claudeModel);
236

237
        // 3. Create an image model
238
        CreateModelRequest dalleModel = CreateModelRequest.builder()
239
            .modelName("dall-e-3")
240
            .matchPattern("dall-e-3")
241
            .unit(ModelUsageUnit.IMAGES)
242
            .totalPrice(0.040)  // $0.04 per image (1024x1024)
243
            .build();
244

245
        client.models().create(dalleModel);
246

247
        // 4. List all models
248
        System.out.println("\nAll models:");
249
        PaginatedModels models = client.models().list();
250
        for (Model model : models.getData()) {
251
            System.out.println("  " + model.getModelName());
252
            if (model.getUnit().isPresent()) {
253
                System.out.println("    Unit: " + model.getUnit().get());
254
            }
255

256
            // Check deprecated price fields
257
            if (model.getInputPrice().isPresent()) {
258
                System.out.println("    Input: $" + model.getInputPrice().get() +
259
                                 " per " + model.getUnit().orElse(ModelUsageUnit.TOKENS));
260
            }
261
            if (model.getOutputPrice().isPresent()) {
262
                System.out.println("    Output: $" + model.getOutputPrice().get() +
263
                                 " per " + model.getUnit().orElse(ModelUsageUnit.TOKENS));
264
            }
265
            if (model.getTotalPrice().isPresent()) {
266
                System.out.println("    Total: $" + model.getTotalPrice().get() +
267
                                 " per " + model.getUnit().orElse(ModelUsageUnit.TOKENS));
268
            }
269

270
            // Check new prices map
271
            if (!model.getPrices().isEmpty()) {
272
                System.out.println("    Prices:");
273
                model.getPrices().forEach((usageType, price) ->
274
                    System.out.println("      " + usageType + ": $" + price.getPrice())
275
                );
276
            }
277
        }
278

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

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

294
        client.models().create(gpt4Updated);
295

296
        // 7. Clean up - delete custom models
297
        // Note: Cannot delete Langfuse-managed models
298
        try {
299
            client.models().delete(gpt4Model.getId());
300
            System.out.println("\nDeleted custom model");
301
        } catch (Exception e) {
302
            System.err.println("Cannot delete: " + e.getMessage());
303
        }
304
    }
305
}
306
```
307

308
## Best Practices
309

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

318
## Pricing Calculation
319

320
Models are used to automatically calculate costs for observations:
321

322
```java
323
// When creating an observation with usage info
324
CreateGenerationEvent generation = CreateGenerationEvent.builder()
325
    .body(CreateGenerationBody.builder()
326
        .id("gen-123")
327
        .traceId("trace-123")
328
        .model("gpt-4-turbo-custom")  // Matches model definition
329
        .usage(IngestionUsage.usageDetails(
330
            UsageDetails.builder()
331
                .input(500)   // 500 tokens
332
                .output(200)  // 200 tokens
333
                .unit(ModelUsageUnit.TOKENS)
334
                .build()
335
        ))
336
        .build())
337
    .build();
338

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

343
## Related Documentation
344

345
- [Traces and Observations](./traces-observations.md) - Using models in observations
346
- [Ingestion API](./ingestion.md) - Creating observations with model info
347
- [Common Types](./common-types.md) - Model type definitions
348
- [Pagination](./pagination.md) - Pagination utilities
349