Funtimes Metadata

Messages API v3 accepts optional Funtimes-specific request metadata under metadata.funtimes.

Only these fields are allowed:

Field	Type	Description
character	String or object	GitHub character reference or inline character object.
character_params	Object	Flat template parameters for the character personality. Values may be string, number, boolean, or null.

All other metadata.funtimes fields are rejected.

GitHub Character

Use a GitHub character reference when the character is saved in Funtimes:

{
  "metadata": {
    "funtimes": {
      "character": "github:partner/CharacterName",
      "character_params": {
        "person_name": "Alex"
      }
    }
  }
}

github-force: is also accepted for force-refresh flows:

{
  "metadata": {
    "funtimes": {
      "character": "github-force:partner/CharacterName"
    }
  }
}

Funtimes validates that the quota is allowed to use the requested character.

Inline Character

Use an inline character object for ad hoc testing or cases where the character is supplied with the request:

{
  "metadata": {
    "funtimes": {
      "character": {
        "parameters": {
          "name": "Mira",
          "language": "en",
          "person_name": "Alex",
          "robot_name": "Mira",
          "name_colon": "Mira:",
          "conversation_prefix": "",
          "interruption_message": "",
          "easy_questions": [],
          "difficult_questions": [],
          "voice": null,
          "greetings": [],
          "max_new_tokens": 128
        },
        "personality": "You are {{ robot_name }}. Be concise and helpful."
      }
    }
  }
}

Inline characters must pass Funtimes character validation. Some existing character schemas include max_new_tokens as legacy character metadata. Messages API v3 does not use character max_new_tokens to control generation length; use request-level token limits instead.

Character Params

character_params are rendered into Jinja character personality templates.

{
  "metadata": {
    "funtimes": {
      "character": "github:partner/CharacterName",
      "character_params": {
        "person_name": "Alex",
        "plan": "premium"
      }
    }
  }
}

Rules:

• character_params must be a JSON object.
• Values must be string, number, boolean, or null.
• character_params.context is reserved and rejected.

Knowledge Context

Knowledge context is configured in the character settings. This works the same way whether the character is referenced from GitHub or supplied inline.

For a GitHub character, configure the knowledge settings in the saved character file and reference the character:

{
  "metadata": {
    "funtimes": {
      "character": "github:partner/CharacterName"
    }
  }
}

For an inline character, include the knowledge settings inside the character parameters object:

{
  "metadata": {
    "funtimes": {
      "character": {
        "parameters": {
          "robot_name": "Mira",
          "rag_index_required": "partner/knowledge-base-name",
          "rag_enabled": true
        },
        "personality": "You are {{ robot_name }}. Use the available knowledge context when relevant."
      }
    }
  }
}

When knowledge context is configured, Messages API v3 may add relevant context automatically before the model answers.

In character settings:

• rag_enabled turns knowledge context on for that character.
• rag_index_required selects which saved knowledge base the character should use.

Model Fallback

Do not send routing config in metadata.funtimes.

Invalid:

{
  "metadata": {
    "funtimes": {
      "routing": {
        "primary_model": "google/gemini-2.5-flash"
      }
    }
  }
}

To request a fallback model, use top-level fallback_model:

{
  "model": "google/gemini-2.5-flash",
  "fallback_model": "qwen/qwen3.6-27b"
}

Messages API v3 uses this as a routing option when supported.

Character models

A character can set its own texting model (llm_texting_model in the character settings). Its fallback models (llm_backend_config.fallback_model, or llm_backend_config.openrouter.fallback_model when the character has an openrouter block, which then replaces the top-level setting) are shared by calls and texting; texting uses the first one listed. Each is used only when the request leaves the field out or blank:

1. model / fallback_model in the request
2. The character's texting model / first fallback model
3. The server default (for the fallback model, the server's fallback setting, if any)

The character's calls model is never used for texting. A request with discounted: true uses no fallback model.

Model Conversation Visibility

metadata.funtimes is Funtimes-only request metadata and is not included in the model conversation. Non-Funtimes metadata is preserved:

{
  "metadata": {
    "client": "kept",
    "funtimes": {
      "character": "github:partner/CharacterName"
    }
  }
}

The model request keeps:

{
  "metadata": {
    "client": "kept"
  }
}