Generate a character and create the agent

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agent_id?string

Pre-existing agent UUID (optional)

description*string

Free-text personality description

fields?array<string>|

Optional list of fields to generate

gender?string

Agent gender (optional; generator infers from description when empty)

language?string

Language for generation

model?string

Optional model override for the chosen provider.

name*string

Agent display name

project_id?string

Project UUID to assign agent to

provider?string

LLM provider for generation (gemini | openrouter | xai). Defaults to gemini.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/generate-and-create" \  -H "Content-Type: application/json" \  -d '{    "description": "string",    "name": "string"  }'

null

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Generate a character profile from a description

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agent_id?string

Pre-existing agent UUID (optional)

description*string

Free-text personality description

fields?array<string>|

Optional list of fields to generate

gender?string

Agent gender (optional; generator infers from description when empty)

model?string

Optional model override for the chosen provider.

name*string

Agent display name

provider?string

LLM provider for generation (gemini | openrouter | xai). Defaults to gemini.

regenerate?boolean

Force regeneration even if agent exists

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/generate-character" \  -H "Content-Type: application/json" \  -d '{    "description": "string",    "name": "string"  }'

null

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Regenerate agent avatar

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

style?string

Avatar art style override

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/avatar/generate" \  -H "Content-Type: application/json" \  -d '{}'

{
  "$schema": "/api/v1/schemas/RegenerateAvatarOutputBody.json",
  "avatar_url": "string",
  "generation_time_ms": 0,
  "prompt": "string",
  "success": true
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Generate agent bio

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

current_bio?string

Current bio to improve upon

description*string

Free-text personality description

enriched_context_json?unknown

Pre-built enriched context (from orchestrator)

gender?string

Agent gender (optional; generator infers from description when empty)

instance_id?string

Agent instance identifier

name*string

Agent display name

style?string

Bio generation style

user_id?string

User ID (from orchestrator)

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/bio/generate" \  -H "Content-Type: application/json" \  -d '{    "description": "string",    "name": "string"  }'

{
  "$schema": "/api/v1/schemas/GenerateBioOutputBody.json",
  "bio": "string",
  "confidence": 0.1,
  "tone": "string"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Generate an image

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model?string

Model to use (default: gemini-3.1-flash-image-preview)

negative_prompt?string

Negative prompt (things to avoid)

output_path?string

GCS output path

prompt*string

Image generation prompt

provider?string

Provider to use (default: gemini)

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/image/generate" \  -H "Content-Type: application/json" \  -d '{    "prompt": "string"  }'

{
  "$schema": "/api/v1/schemas/GenerateImageOutputBody.json",
  "gcs_uri": "string",
  "generation_time_ms": 0,
  "image_id": "string",
  "mime_type": "string",
  "public_url": "string",
  "success": true
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Generate seed memories for an agent

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agentName*string

Agent display name

big5?

Big Five personality scores

creatorDisplayName?string

Creator's display name

generateOriginStory?boolean

Whether to generate origin story

generatePersonalizedMemories?boolean

Whether to generate personalized memories

identityMemoryTemplates?array<>|

Identity memory templates

loreGenerationContext?

Lore generation context

personalityPrompt*string

Personality prompt text

primaryTraits?array<string>|

Primary personality traits

speechPatterns*array<string>|

Agent's speech patterns

staticLoreMemories?array<>|

Pre-defined lore memories

trueDislikes?array<string>|

Agent's true dislikes

trueInterests*array<string>|

Agent's true interests

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/memory/seed" \  -H "Content-Type: application/json" \  -d '{    "agentName": "string",    "personalityPrompt": "string",    "speechPatterns": [      "string"    ],    "trueInterests": [      "string"    ]  }'

{
  "$schema": "/api/v1/schemas/GenerateSeedMemoriesOutputBody.json",
  "memories": [
    {
      "content": "string",
      "entities": [
        "string"
      ],
      "factType": "string",
      "importance": 0.1
    }
  ]
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Generation

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

200application/json

defaultapplication/problem+json

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/json`

`application/problem+json`