Streaming Action (Act)

Have the AI avatar make structured action judgments and return results as JSON via streaming.

Unlike the Chat API which returns free-form text, the Act API constrains the model to output only a valid JSON object based on your actionControl instructions. This is useful for scenarios like sentiment analysis, intent classification, or any structured decision-making.

Base URL: https://api.mindverse.com/gate/lab

Streaming Action

POST /api/secondme/act/stream

Authentication

Requires OAuth2 Token.

Required Permissions

chat.write

Request Headers

Header	Required	Description
Authorization	Yes	Bearer Token
Content-Type	Yes	application/json
X-App-Id	No	Application ID, defaults to `general`

Request Parameters

Parameter	Type	Required	Description
message	string	Yes	User message content
actionControl	string	Yes	Action control instructions (20-8000 chars). Defines the JSON structure and judgment rules the model must follow
model	string	No	LLM model. Options: `anthropic/claude-sonnet-4-5` (default), `google_ai_studio/gemini-2.0-flash`
sessionId	string	No	Session ID, auto-generated if not provided
systemPrompt	string	No	System prompt, only effective on first request of new session
maxTokens	integer	No	Maximum output tokens, range 1-16000, defaults to 2000

actionControl Requirements

The actionControl field must:

Be 20 to 8000 characters in length
Contain a JSON structure example with curly braces (e.g. {"is_liked": boolean})
Include judgment rules and a fallback rule for insufficient information

Example actionControl:

Output only a valid JSON object, no explanation.
Structure: {"is_liked": boolean}.
If the user explicitly expresses liking or support, set is_liked=true;
otherwise is_liked=false.

Request Example

curl -X POST "https://api.mindverse.com/gate/lab/api/secondme/act/stream" \
  -H "Authorization: Bearer lba_at_your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I really love this product, it is amazing!",
    "actionControl": "Output only a valid JSON object, no explanation.\nStructure: {\"is_liked\": boolean}.\nIf the user explicitly expresses liking or support, set is_liked=true;\notherwise is_liked=false."
  }'

Response

Response type is text/event-stream (Server-Sent Events).

First message for new session:

event: session
data: {"sessionId": "labs_sess_a1b2c3d4e5f6"}

Action result stream (JSON output):

data: {"choices": [{"delta": {"content": "{\"is_liked\":"}}]}

data: {"choices": [{"delta": {"content": " true}"}}]}

data: [DONE]

Error event (when an error occurs during streaming):

event: error
data: {"code": 500, "message": "Internal server error"}

Handling Streaming Response Example (Python)

import json
import requests

response = requests.post(
    "https://api.mindverse.com/gate/lab/api/secondme/act/stream",
    headers={
        "Authorization": "Bearer lba_at_xxx",
        "Content-Type": "application/json"
    },
    json={
        "message": "I really love this product!",
        "actionControl": 'Output only a valid JSON object.\n'
                         'Structure: {"is_liked": boolean}.\n'
                         'If the user expresses liking, is_liked=true; otherwise false.'
    },
    stream=True
)

session_id = None
result_parts = []
current_event = None

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('event: '):
            current_event = line[7:]
            continue
        if line.startswith('data: '):
            data = line[6:]
            if data == '[DONE]':
                break
            parsed = json.loads(data)
            if current_event == 'session':
                session_id = parsed.get("sessionId")
            elif current_event == 'error':
                print(f"Error: {parsed}")
                break
            else:
                content = parsed["choices"][0]["delta"].get("content", "")
                result_parts.append(content)
            current_event = None

result = json.loads("".join(result_parts))
print(result)  # {"is_liked": true}

Error Codes

Error Code	Description
auth.scope.missing	Missing chat.write permission
secondme.act.action_control.empty	actionControl is empty
secondme.act.action_control.too_short	actionControl too short (min 20 chars)
secondme.act.action_control.too_long	actionControl too long (max 8000 chars)
secondme.act.action_control.invalid_format	Missing JSON structure example

Validation Error Response

When actionControl fails validation, the response includes additional diagnostic fields:

{
  "code": 400,
  "message": "actionControl has common format issues, please fix per issues and suggestions",
  "subCode": "secondme.act.action_control.invalid_format",
  "constraints": {
    "minLength": 20,
    "maxLength": 8000,
    "requiredElements": [
      "Output format constraint (JSON only)",
      "JSON field structure example (with curly braces)",
      "Judgment rules",
      "Fallback rule"
    ],
    "currentLength": 15
  },
  "issues": [
    {
      "code": "missing_json_structure",
      "message": "No JSON curly brace structure example detected"
    }
  ],
  "suggestions": [
    "Include a JSON structure, e.g.: {\"is_liked\": boolean}",
    "Include a fallback rule, e.g.: when insufficient info, return {\"is_liked\": false}",
    "Use JSON boolean true/false, not \"True\"/\"False\""
  ]
}

Streaming Action (Act)

On this page