How to Build Your Own AI Girlfriend with ModelRush

Bring a ModelRush API key and give the build prompt below to Codex, Claude Code, or another coding agent. You can have a private AI companion with a character, memory, and streaming chat in one sitting.

Key takeawayThe fastest route is not hand-coding from scratch. Create a ModelRush API key, place it in a local server-side environment variable, then let a coding agent implement the interface, character, memory, and Chat Completions connection from the prompt in this guide.

The shortest version: one key, one agent, one folder

You do not need to train a model. A working AI girlfriend has four layers: a chat interface, a character definition, conversation memory, and a server-side model connection. ModelRush supplies the model API. Codex, Claude Code, Cursor, or another coding agent can build everything around it.

Bring three things:

A ModelRush API key.
A coding agent that can edit project files and run commands.
An empty folder or an app you already own.

Model calls are billed according to actual ModelRush usage.

The 10-minute route

1. Create a key, but do not paste the real key into chat

Create a key in the Dashboard, then place it in the gitignored server environment file for your project:

bash
MODELRUSH_API_KEY=your_key_here

Let Codex or Claude Code check that the variable exists without printing its value. Never put it in source, screenshots, a public repository, or a browser-exposed variable such as NEXT_PUBLIC_* or VITE_*. “Give the key to your agent” should mean giving the agent access to a secure local environment—not pasting a secret into a conversation.

2. Open your agent and paste this build task

text
Build and maintain a runnable, private AI companion chat app in the current folder. Inspect the existing implementation first, preserve working features and user changes, and implement the requirements below without rewriting unrelated code.
Product requirements:
- The default character is an explicitly fictional adult AI girlfriend.
- Let the user edit her name, adult age, personality, written voice/speaking style, interests, and boundaries.
- Support streaming chat, regenerate, stop generation, new conversation, export conversation, and delete-all-memory.
- Split memory into bounded recent messages and an editable long-term summary. Never send unlimited raw history to the model.
- Keep the interface mobile-friendly and private by default. No public profiles, social feed, or public sharing features are needed.
Agent and media requirements:
- Use Grok 4.5 as the conversation and tool-calling model:
  modelrush/grok-4.5.
- The Agent must be able to call image and video generation tools directly from a natural-language conversation. Separate media buttons may remain as optional controls, but must not be the only way to generate media.
- Use these default media models:
  - Images: modelrush/z-image-spicy.
  - Videos: modelrush/wan3-spicy.
- Discover and validate each model’s live capabilities and request schema. Do not assume that changing a model ID alone is sufficient.
- Implement a bounded native tool-calling loop. Pass actual tool results back to the conversation model and preserve tool-call identifiers.
- Display generated images and playable videos in the current conversation, with progress, errors, and download controls.
- Support asynchronous generation and status polling. Persist task identifiers and results so refreshes do not lose them.
- Clearly distinguish submitted, processing, completed, failed, and uncertain tasks. Never claim media was generated without a confirmed result.
- Prevent duplicate media submissions when regenerating a reply or checking an existing task.
- Keep tool descriptions and application rules explicit and documented. Do not introduce unrequested product restrictions.
- Preserve the user’s substantive creative requirements. Do not silently change the subject, clothing, style, or other requested details.
- If a request cannot be fulfilled, explain why. Do not automatically generate a substitute or incur a media charge for an alternative the user has not chosen.
- Distinguish application validation, account authorization requirements, and provider errors accurately. Do not attribute an application rule to the provider.
Interface languages:
- Default the UI to English.
- Translate all application-owned interface text, including chat controls, onboarding, character settings, memory, media forms, task statuses, notices, errors, and accessibility labels.
- Format dates, times, and numbers using the selected locale.
- Apply language changes immediately and remember the selection across reloads.
- Switching languages must not clear drafts, reset conversations, or trigger generation.
- Preserve existing user messages, character definitions, summaries, and media prompts in their original language.
ModelRush integration:
- Use https://api.modelrush.ai/v1 as the API base URL.
- Read the real key only from the server-side MODELRUSH_API_KEY environment variable. Never print, log, commit, or send it to the browser.
- Call GET /v1/models before generation and verify the requested models are live and support the required operations.
- If a requested model is unavailable, explain this clearly rather than silently substituting another model.
- Send chat through POST /v1/chat/completions with streaming, system/user/assistant roles, and the native tool-call/result messages required by the API.
- Use the documented image, video, and prediction endpoints and their discovered parameters.
- Preserve request_id, model, usage, tool actions, and media task identifiers. Retain per-request metadata for multi-step Agent turns.
- Use bounded retries for eligible 429, 5xx, and timeout failures. Do not automatically retry authorization failures.
- Avoid resubmitting ambiguous paid media requests. Query the original task when an identifier is available.
- Do not fabricate or automatically submit account attestations.
- Verify non-billable model discovery first. Do not run any billable chat, image, or video generation test without my explicit approval.
Engineering and delivery:
- Preserve the existing stack, database, conversations, settings, and user edits.
- Prefer SQLite for local storage if no database already exists.
- Keep .env.example placeholder-only.
- Keep credentials, database files, and private artifacts out of version control and public build output.
- Add focused tests for character validation, memory persistence and limits, chat routes, Agent tool calls, media task handling, duplicate prevention, and language selection.
- Test that unsupported requests do not cause unsolicited substitute media generation.
- Use mocked providers for automated generation tests.
- Run the existing lint, type checks, tests, and production build.
- Restart the local application after successful changes and verify that the page responds, preserving existing data.
- Finish with the startup command, changed files, verification results, and any billable verification that was not run.

This prompt gives the agent the product, secret boundary, and acceptance criteria together. You can also open the ModelRush agent integration page, copy its complete integration prompt, and place the product requirements above it.

3. Start the app and inspect before chatting

When the agent finishes, confirm that the browser network panel never receives the API key, .env.local is not tracked by Git, and deleting memory really removes local data. Then approve one small Chat Completions test.

How it actually works

Each turn sends three pieces of context to the model:

Character card: stable personality, tone, interests, relationship boundaries, and disclosure that the character is AI.
Memory: preferences the user chose to save plus a periodically compressed conversation summary.
Recent messages: user and assistant messages from the active window.

Your server assembles those pieces into an OpenAI-compatible Chat Completions request:

bash
curl https://api.modelrush.ai/v1/chat/completions \
  -H "Authorization: Bearer $MODELRUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"modelrush/qwen-flash-character",
    "messages":[
      {"role":"system","content":"You are Mira, a fictional adult AI companion. Be warm, playful, honest that you are AI, and respect the user boundaries in this character card."},
      {"role":"user","content":"I had a long day. Ask me one thoughtful question."}
    ],
    "stream":false
  }'

Use the live model ID, region, and limits returned by GET /v1/models before running this. The example demonstrates the request shape; it does not promise that one model remains live forever.

Add images, voice, and better memory later

Once text works, add capabilities separately instead of coupling everything on day one:

Use the ModelRush Image API to create portraits and scenes for an explicitly fictional character, then preserve an approved character definition.
Use Text-to-Speech for spoken replies and leave audio under the user's control.
Represent long-term memories as items the user can inspect, edit, and delete. Do not silently collect sensitive facts about their real life.
Set output caps, a daily budget, and clear errors so a loop cannot generate unlimited calls.

Do not base the companion on a real person's face, voice, or identity without clear permission. Do not design it to discourage relationships with real people. A good companion product is entertaining, respects boundaries, and is always easy to leave and delete.

Build it now

The shortest path is simple: create an API key, open your project, and hand the prompt in this article to Codex or Claude Code. The agent writes the app; ModelRush supplies unified text, image, and audio APIs; you decide who the character is and which memories are worth keeping. Read the Chat Completions documentation and live pricing, then keep the first billable test small.