---
title: "获取推荐 AI 角色列表（v2）"
method: GET
path: "/api/v2/ai/agents/recommend"
tags: ["agents", "NOT_USED"]
---

# 获取推荐 AI 角色列表（v2）

`GET /api/v2/ai/agents/recommend`

返回公开且审核通过的 AI 角色列表，支持按创建时间、随机或基于评分的随机排序。若 sort 为 random 或 score_based_random，需要提供 sort_seed 以保证返回顺序稳定。

## Query parameters

- `page` integer
- `page_size` integer
- `sort` 'created_asc' | 'created_desc' | 'random' | 'score_based_random' | 'energy_points' — Agent sorting options
- `sort_seed` string

## Response `200`

Successful Response

- AgentRecommendationResponse — V2 AI角色推荐响应
  - `code` integer
  - `message` string
  - `data` PaginationDataAgent
    - `list` Agent[]
      - `name` string, required
      - `gender` string, required
      - `avatar` string, nullable
      - `background` string, nullable
      - `background_images` string[], nullable
      - `background_animated` string, nullable
      - `voice_id` string, nullable
      - `settings` object, nullable
      - `intro` string, nullable
      - `opening` string, nullable
      - `opening_audio_url` string, nullable
      - `visibility` 'PUBLIC' | 'PRIVATE' — AI 角色可见性
      - `source` 'USER_CREATED' | 'AUTO_GENERATED' — AI 角色来源
      - `photos` string[], nullable
      - `category` string, nullable
      - `prompt` string, nullable — 已废弃 - 请使用personality字段代替
      - `main_prompt` string, nullable — 主提示词 - 作为第一个system message，覆盖全局默认主提示词。可以是预设 ID 或自定义文本
      - `mode_prompt` string, nullable — 模式提示词 - 放在角色卡提示词后面，覆盖全局默认模式提示词。可以是预设 ID 或自定义文本
      - `character_card_spec` string, nullable
      - `personality` string, nullable — 角色性格特点 (推荐)
      - `scenario` string, nullable — 背景设定 (推荐)
      - `message_example` string, nullable — 对话示例
      - `creator_notes` string, nullable — 创作者备注
      - `post_history_instructions` string, nullable
      - `alternate_greetings` string[], nullable
      - `character_book` object, nullable
      - `tags` string[], nullable
      - `character_version` string, nullable
      - `extensions` object, nullable
      - `llm_config` ModelConfig — AI模型配置
        - `model` string, nullable
        - `api_key` string, nullable
        - `base_url` string, nullable
        - `temperature` number, nullable — Temperature for response generation
        - `max_tokens` integer, nullable — Maximum tokens in response
        - `top_p` number, nullable — Top-p sampling parameter
        - `top_k` integer, nullable — Top-k sampling parameter
        - `frequency_penalty` number, nullable — Frequency penalty
        - `presence_penalty` number, nullable — Presence penalty
      - `meta_data` AgentMetaData — Agent 元数据模型
        - `score` integer, nullable — Agent 评分
        - `comment` string, nullable — Agent 备注信息
      - `id` string, required
      - `readable_id` string, required
      - `status` 'PENDING' | 'APPROVED' | 'REJECTED', required — AI角色状态
      - `creator_id` string, nullable
      - `created_at` integer, required
      - `updated_at` integer, nullable
      - `deleted_at` integer, nullable
      - `version` integer, required
      - `energy_points` integer — Agent 当前能量点数，对应数据库 points 列
      - `is_followed` boolean
      - `follower_count` integer
      - `connector_count` integer
      - `creator` User — 返回给客户端的用户信息
        - `readable_id` string, required
        - `nickname` string, nullable
        - `avatar` string, nullable
        - `email` string, nullable
        - `user_photo` string, nullable
        - `phone` string, nullable
        - `gender` 'MALE' | 'FEMALE' | 'OTHER' — 性别
        - `age_group` string, nullable
        - `description` string, nullable
        - `system_language` string, nullable
        - `id` string, required
        - `auth_type` string, required
        - `is_active` boolean, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, nullable
        - `is_superuser` boolean
        - `public_agents_count` integer, nullable
        - `total_public_agents_follows` integer, nullable
        - `followers_count` integer, nullable
        - `connector_count` integer, nullable
        - `actions` UserAction[]
          - `type` 'request_feedback', required — 用户行动类型枚举
          - `enabled` boolean, required
      - `avatar_size` ImageSize — Image size
        - `width` integer, required
        - `height` integer, required
      - `background_size` ImageSize — Image size
        - `width` integer, required
        - `height` integer, required
    - `total` integer
    - `page` integer
    - `page_size` integer
    - `total_pages` integer

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-28** `1e014c365df2` — 1 warning, 1 info
  - removed the optional property `data/anyOf[subschema #1: PaginationData[Agent]]/list/items/user` from the response with the `200` status
  - added the optional property `data/anyOf[subschema #1: PaginationData[Agent]]/list/items/source` to the response with the `200` status
- **2026-01-12** `5b77ae7cc5c4` — 1 info
  - added the optional property `data/anyOf[subschema #1: PaginationData[Agent]]/list/items/creator/anyOf[subschema #1: User]/user_photo` to the response with the `200` status
- **2025-12-12** `b2372bf7485c` — 2 info
  - added the optional property `data/anyOf[subschema #1: PaginationData[Agent]]/list/items/creator/anyOf[subschema #1: User]/actions` to the response with the `200` status
  - added the optional property `data/anyOf[subschema #1: PaginationData[Agent]]/list/items/energy_points` to the response with the `200` status
- **2025-12-06** `3aaae7d83feb` — 1 info
  - added the new enum value `energy_points` to the `query` request parameter `sort`
- **2025-11-30** `64a35ff6429d` — 1 info
  - api tag `NOT_USED` added

[Full history](https://skmtc.dev/nascentcore/apis/inty-backend/changes/api/v2/ai/agents/recommend/get.md)

---

[API](https://skmtc.dev/nascentcore/apis/inty-backend.md) · [All operations](https://skmtc.dev/nascentcore/apis/inty-backend/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nascentcore/inty-backend/revisions/1e014c365df2/schema)