---
title: "Create new AI agent"
method: POST
path: "/api/v1/ai/agents"
tags: ["agents", "characters", "android_app", "web_app", "evaluation"]
---

# Create new AI agent

`POST /api/v1/ai/agents`

Create new AI agent, used by app and inty-eval

## Request body

- AgentCreate — 创建AI角色 推荐使用方式： 1. 使用personality + scenario字段构建角色 2. 添加first_message作为开场白 3. 可选添加message_example展示对话风格 兼容性说明： - 仍支持使用prompt字段 (legacy模式) - 优先级：角色卡字段 > prompt字段
  - `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 备注信息
  - `request_id` string, nullable

## Response `200`

Successful Response

- APIResponseUnionAgentDictStrAny
  - `code` integer
  - `message` string
  - `data` union
    - Agent — AI角色，在 sqlalchemy 模型基础上添加额外多表查询来的数据
      - `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
    - object

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-28** `1e014c365df2` — 1 warning, 2 info
  - removed the optional property `data/anyOf[subschema #1: Agent]/user` from the response with the `200` status
  - added the new optional request property `source`
  - added the optional property `data/anyOf[subschema #1: Agent]/source` to the response with the `200` status
- **2026-01-12** `5b77ae7cc5c4` — 1 info
  - added the optional property `data/anyOf[subschema #1: Agent]/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: Agent]/creator/anyOf[subschema #1: User]/actions` to the response with the `200` status
  - added the optional property `data/anyOf[subschema #1: Agent]/energy_points` to the response with the `200` status
- **2025-11-25** `05cf5f034c74` — 8 info
  - api tag `android_app` added
  - api tag `evaluation` added
  - api tag `web_app` added
  - api tag `app` removed
  - …4 more
- **2025-10-21** `0ee1ca2e37cb` — 1 info
  - added `subschema #2` to the `data` response property `anyOf` list for the response status `200`

[Full history](https://skmtc.dev/nascentcore/apis/inty-backend/changes/api/v1/ai/agents/post.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)