# How to Integrate Custom AI Models with AiToEarn: A Complete Developer Guide

> Learn how to integrate custom AI models with AiToEarn. This developer guide explains backend configuration, AiService endpoints, and frontend API wrappers for seamless integration without UI changes.

- Repository: [yikart/AiToEarn](https://github.com/yikart/AiToEarn)
- Tags: how-to-guide
- Published: 2026-05-12

---

**You can integrate custom AI models into AiToEarn by defining model parameters in the backend configuration DTOs, exposing them through the generic `AiService` endpoints, and consuming them via the frontend API wrappers in [`src/api/ai.ts`](https://github.com/yikart/AiToEarn/blob/main/src/api/ai.ts) without modifying any UI components.**

AiToEarn uses a modular architecture that separates **model definition**, **backend service exposure**, and **frontend consumption** to streamline AI monetization workflows. Integrating custom large language models (LLMs), image generators, or video synthesis engines requires updating the NestJS backend configuration and ensuring the Next.js frontend recognizes the new capabilities through existing API contracts.

## Architecture Overview

The integration follows a three-tier flow that keeps UI changes minimal while maximizing backend flexibility:

1. **Model Definition** – Declare the model’s capabilities, parameters, and metadata in TypeScript interfaces and DTOs stored in the `models-config` module.
2. **Service Exposure** – The `AiService` class reads these definitions from internal endpoints (`/internal/ai/models/*`) and routes generation requests to the appropriate provider.
3. **Client Consumption** – The frontend fetches available models via the public API wrappers in [`project/aitoearn-web/src/api/ai.ts`](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-web/src/api/ai.ts) and dynamically populates selection dropdowns based on the returned configuration.

## Step 1 – Define the Custom Model Configuration

Add your custom model to the backend by extending the appropriate value object (VO) or DTO. The system supports chat completions, image generation, and video generation through distinct interfaces.

### Configuring Chat Models

Update the interface in [`ai.interface.ts`](https://github.com/yikart/AiToEarn/blob/main/ai.interface.ts) to include your model’s specifications:

```typescript
// project/aitoearn-backend/libs/aitoearn-ai-client/src/interfaces/ai.interface.ts
export interface ChatModelConfigVo {
  name: string;          // Unique identifier used in API calls
  displayName: string;   // Human-readable label for UI
  maxTokens: number;
  temperature: number;
  // Add custom fields as needed for your provider
}

```

Then register the model in the configuration DTO:

```typescript
// project/aitoearn-backend/apps/aitoearn-ai/src/core/ai/models-config/models-config.dto.ts
export class ModelsConfigDto {
  chatModels: ChatModelConfigVo[] = [
    {
      name: 'gpt-custom-v1',
      displayName: 'GPT Custom v1',
      maxTokens: 8192,
      temperature: 0.7,
    },
  ];
}

```

### Configuring Image and Video Models

For diffusion or video models, extend `ImageGenerationModelParamsVo` or `VideoGenerationModelParamsVo`:

```typescript
// Example for a custom Stable Diffusion endpoint
export const customImageModels: ImageGenerationModelParamsVo[] = [
  {
    name: 'stable-diffusion-custom',
    displayName: 'My Custom SD',
    sizeOptions: ['512x512', '1024x1024'],
    // Provider-specific parameters
  },
];

```

## Step 2 – Expose the Model via the Backend Service

The [`AiService`](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-backend/libs/aitoearn-ai-client/src/clients/ai.service.ts) class handles all communication with the internal AI engine. It automatically exposes any models defined in the configuration DTO through dedicated getter methods.

### Internal Endpoint Exposure

The service retrieves chat models using a POST request to the internal router:

```typescript
// In AiService (project/aitoearn-backend/libs/aitoearn-ai-client/src/clients/ai.service.ts)
async getChatModels(data: { userId?: string; userType?: UserType }) {
  const url = `/internal/ai/models/chat`;
  const config: AxiosRequestConfig = { method: 'POST', data };
  return this.request<ChatModelConfigVo[]>(url, config);
}

```

Similar methods exist for image and video models (`getImageGenerationModels` and `getVideoGenerationModels`). Because these methods read directly from the configuration DTO, your custom model appears in the API response immediately after you update the DTO and restart the service.

### Routing Generation Requests

When the frontend triggers generation, the backend forwards the request to the custom model’s endpoint using the `model` parameter from the payload:

```typescript
async videoGeneration<T>(data: VideoGenerationModelParamsVo) {
  const url = `/internal/ai/generate/video`;
  // The 'model' field in data determines the target provider
  return this.request<T>(url, { method: 'POST', data });
}

```

## Step 3 – Consume the Model in the Frontend

The web client fetches the model list and renders selectors without hardcoded model names, enabling seamless integration of custom backends.

### Fetching Available Models

Import the API wrappers from the ai module:

```typescript
// project/aitoearn-web/src/api/ai.ts
import { 
  getChatModels, 
  getImageGenerationModels, 
  getVideoGenerationModels 
} from '@/api/ai';

async function loadModelOptions() {
  const [chatModels, imageModels, videoModels] = await Promise.all([
    getChatModels(),
    getImageGenerationModels(),
    getVideoGenerationModels(),
  ]);
  
  // Populate state for dropdown components
  return {
    chat: chatModels.data,
    image: imageModels.data,
    video: videoModels.data,
  };
}

```

### Triggering Generation with Custom Models

Pass the selected model name to the generation function exactly as it appears in the configuration:

```typescript
import { generateImage } from '@/api/ai';

async function createCustomImage(prompt: string, modelName: string) {
  // modelName must match the 'name' field from ImageGenerationModelParamsVo
  const response = await generateImage({
    prompt,
    model: modelName,      // e.g., 'stable-diffusion-custom'
    size: '512x512',
  });
  return response.data;
}

```

The [`generateImage`](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-web/src/api/ai.ts) function (lines 24‑35) POSTs to `/api/ai/generate/image`, which the backend routes to your custom provider based on the `model` parameter.

## End-to-End Integration Example

Below is a complete workflow adding a custom image generation model:

```typescript
// 1. Backend – Define the model (ai.interface.ts)
export interface ImageGenerationModelParamsVo {
  name: string;               // 'my-custom-model'
  displayName: string;        // 'My Custom AI'
  sizeOptions: string[];      // ['256x256', '512x512']
}

// 2. Backend – Add to config DTO (models-config.dto.ts)
export const modelConfig = {
  imageModels: [
    { name: 'my-custom-model', displayName: 'My Custom AI', sizeOptions: ['512x512'] }
  ]
};

// 3. Frontend – Fetch and use (React component)
import { useEffect, useState } from 'react';
import { getImageGenerationModels, generateImage } from '@/api/ai';

export function ImageGenerator() {
  const [models, setModels] = useState<ImageGenerationModelParamsVo[]>([]);
  
  useEffect(() => {
    getImageGenerationModels().then(res => setModels(res.data));
  }, []);
  
  const handleGenerate = async (prompt: string, modelName: string) => {
    const result = await generateImage({ prompt, model: modelName });
    console.log(result.url);
  };
  
  return (
    <select>
      {models.map(m => (
        <option key={m.name} value={m.name}>{m.displayName}</option>
      ))}
    </select>
  );
}

```

## Key Files Reference

| File | Purpose | GitHub Link |
|------|---------|-------------|
| [`src/api/ai.ts`](https://github.com/yikart/AiToEarn/blob/main/src/api/ai.ts) | Frontend API wrappers for fetching models and triggering generation | [src/api/ai.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-web/src/api/ai.ts) |
| [`ai.service.ts`](https://github.com/yikart/AiToEarn/blob/main/ai.service.ts) | Backend client that calls internal AI endpoints and returns model configurations | [libs/aitoearn-ai-client/src/clients/ai.service.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-backend/libs/aitoearn-ai-client/src/clients/ai.service.ts) |
| [`ai.interface.ts`](https://github.com/yikart/AiToEarn/blob/main/ai.interface.ts) | TypeScript definitions for chat, image, and video model parameters | [libs/aitoearn-ai-client/src/interfaces/ai.interface.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-backend/libs/aitoearn-ai-client/src/interfaces/ai.interface.ts) |
| [`models-config.dto.ts`](https://github.com/yikart/AiToEarn/blob/main/models-config.dto.ts) | DTO that validates and transports model-config payloads | [apps/aitoearn-ai/src/core/ai/models-config/models-config.dto.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-backend/apps/aitoearn-ai/src/core/ai/models-config/models-config.dto.ts) |
| [`AiBatchGenerateBar/constants.ts`](https://github.com/yikart/AiToEarn/blob/main/AiBatchGenerateBar/constants.ts) | UI component constants that build the model-selection interface | [draft-box/AiBatchGenerateBar/constants.ts](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-web/src/app/\[lng\]/draft-box/components/AiBatchGenerateBar/constants.ts) |

## Summary

- **Define** your custom model by adding entries to `ChatModelConfigVo`, `ImageGenerationModelParamsVo`, or `VideoGenerationModelParamsVo` in the backend interfaces and DTOs.
- **Expose** the model automatically through `AiService.getChatModels()`, `getImageGenerationModels()`, or `getVideoGenerationModels()`, which read from the configuration DTO and serve internal endpoints.
- **Consume** the model in the frontend by calling `getChatModels()`, `getImageGenerationModels()`, or `getVideoGenerationModels()` from [`src/api/ai.ts`](https://github.com/yikart/AiToEarn/blob/main/src/api/ai.ts), then passing the selected `name` to the respective generation function.
- **Match exactly** the model identifier between backend configuration and frontend API calls to ensure proper routing.

## Frequently Asked Questions

### Do I need to modify the frontend code to add a new custom model?

No. The frontend dynamically renders model dropdowns based on the data returned by `getChatModels`, `getImageGenerationModels`, and `getVideoGenerationModels`. As long as your backend DTO includes the new model, it will appear in the UI automatically without touching React components.

### What parameters are required when defining an image generation model?

According to the `ImageGenerationModelParamsVo` interface in [[`ai.interface.ts`](https://github.com/yikart/AiToEarn/blob/main/ai.interface.ts)](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-backend/libs/aitoearn-ai-client/src/interfaces/ai.interface.ts), you must provide at minimum a `name` (unique identifier), `displayName` (UI label), and `sizeOptions` (array of supported resolutions). Additional provider-specific fields can be added to the interface as optional properties.

### How does the backend route requests to the correct custom model endpoint?

The backend `AiService` forwards the `model` parameter from the request payload (e.g., the `model` field in `VideoGenerationModelParamsVo`) to the internal AI engine. The engine matches this identifier against the configuration DTO to determine which provider endpoint should handle the generation, requiring no code changes in the service logic when adding new models.

### Can I add multiple custom models simultaneously?

Yes. The `ModelsConfigDto` accepts arrays for each model type (`chatModels`, `imageModels`, `videoModels`). You can seed the database or populate the DTO with multiple entries, and all will be exposed through the same `get*Models` endpoints immediately upon deployment.