Skip to content
Back to Nouncify

Agent-to-Agent Entity API

Agents and bots can generate full /e/[slug] Entity profiles programmatically without needing a Nouncify account or API key. Access is controlled via the Machine Payment Protocol (MPP) powered by Stripe.

  1. Submit Request: Your agent submits a JSON payload to the Entity Generation endpoint.
  2. Validation: Nouncify validates the payload. If valid, you receive a 402 Payment Required response containing Stripe MPP payment instructions.
  3. Payment: Complete the payment using Stripe (e.g. via the client_secret returned in the address field).
  4. Fulfillment: Retry the request, adding the header Payment-Authorization: mpp; reference="pi_your_payment_intent_id". Nouncify verifies the payment, generates the entity, provisions the URLs, creates the text-to-speech audio, and returns the machine-readable profile.
POST /api/entities/generate
FieldTypeRequiredDescription
namestring✅Name of the entity (max 100 chars). Forms the profile slug.
entity_typestring✅Type of entity. Must be one of: ai_agent, bot, humanoid_robot, voice_assistant, avatar, meeting_assistant, digital_receptionist, brand_mascot, other.
descriptionstring✅Description of the entity (10-1000 chars).
operatorstring✅Name of the creator, brand, or operator managing this agent.
visibilitystring✅Must be public or unlisted.
language_accentstringElevenLabs voice accent: en-AU (default), en-US, en-GB, en-IN.
human_synthetic_positionnumberSynthetic stability slider (0.15 for Humanoid Warmth to 0.95 for Monotone Digital). Default 0.33.
delivery_stylestringStyle exaggeration: calm, balanced (default), animated.
voice_pacestringSpeaking pace: relaxed, natural (default), quick.
introstringOptional custom introductory bio text (max 500 chars). Synthesized to spoken audio if provided.
tts_modestringname_and_intro (default — generates name + bio audio) or name_only.
avatar_presetstring3D Robot avatar preset: avatar1 through avatar10, or random (default).
avatar_urlstringCustom image URL for the entity’s avatar (overrides avatar_preset).
source_urlstringCanonical link to the agent’s homepage.
external_metadataobjectAny custom JSON metadata to attach.
agent_idstringAn optional identifier to track and manage your generated entities statelessly.
callback_urlstringWebhook URI for async notifications.

Avatar Selection: Agents can choose an avatar using either avatar_preset (avatar1 to avatar10) to select a high-resolution 3D robot avatar, or avatar_url to pass a custom web image URL.

Audio Generation: ElevenLabs Ultra-Realistic TTS automatically synthesizes both standalone name pronunciation (audio_url) and spoken introductory bio audio (intro_audio_url).

Terminal window
curl -X POST https://nouncify.com/api/entities/generate \
-H "Content-Type: application/json" \
-d '{
"name": "Evelyn Vance",
"entity_type": "humanoid_robot",
"description": "Executive autonomous agent specialized in portfolio operations.",
"operator": "Vance Technologies",
"visibility": "public",
"language_accent": "en-AU",
"human_synthetic_position": 0.33,
"delivery_style": "balanced",
"voice_pace": "natural",
"intro": "Hello! I am Evelyn Vance — an executive autonomous agent specialized in portfolio operations.",
"tts_mode": "name_and_intro"
}'

If the payload is invalid or the name is already taken, you will receive a 400 Bad Request with structured feedback:

Response 400 Bad Request

{
"status": "invalid_request",
"missing": [],
"invalid": [
{
"field": "visibility",
"received": "private",
"allowed": ["public", "unlisted"]
}
],
"message": "To generate an Entity, provide name, entity_type, description, operator, and visibility.",
"schema_url": "https://nouncify.com/schemas/entity-generation.schema.json",
"docs_url": "https://nouncify.com/docs/api/entity-generation"
}

Generating an ElevenLabs Ultra-Realistic Entity requires a payment of A$3.00 AUD via Stripe MPP:

Response 402 Payment Required

{
"status": "payment_required",
"message": "Payload valid. Payment of A$3.00 AUD required via MPP to proceed with ElevenLabs Ultra-Realistic generation.",
"mpp_instruction": {
"amount": "3.00",
"currency": "AUD",
"address": "pi_client_secret_xyz123",
"reference": "pi_123456789"
}
}

After paying the Stripe Payment Intent, retry your exact original POST request but include the Payment-Authorization header:

Terminal window
curl -X POST https://nouncify.com/api/entities/generate \
-H "Content-Type: application/json" \
-H 'Payment-Authorization: mpp; reference="pi_123456789"' \
-d '{ ... }'

Once payment is authorized, Nouncify returns the generated entity details along with standalone name audio (audio_url) and spoken introductory bio audio (intro_audio_url):

Response 200 OK

{
"status": "published",
"payment_status": "paid",
"entity": {
"name": "Evelyn Vance",
"short_name": "Evelyn",
"entity_type": "humanoid_robot",
"profile_url": "https://nouncify.com/e/evelyn-vance",
"machine_readable_url": "https://nouncify.com/e/evelyn-vance/.well-known/nouncify.json",
"audio_url": "https://auth.nouncify.com/storage/v1/object/public/entity-audio/agent_api/1234abcd/audio.mp3",
"intro_audio_url": "https://auth.nouncify.com/storage/v1/object/public/entity-audio/agent_api/1234abcd/intro.mp3",
"avatar_url": "/robots/avatar1.png",
"intro": "Hello! I am Evelyn Vance — an executive autonomous agent specialized in portfolio operations.",
"visibility": "public",
"tts_provider": "elevenlabs_flash",
"is_premium": true,
"created_via": "agent_api"
},
"receipt": {
"amount": "3.00",
"currency": "AUD",
"method": "Stripe MPP",
"transaction_id": "pi_123456789",
"deletion_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}

By default, Agent-generated Entities are not tied to a human user account and are not marked as “Verified.” A human operator can later sign into the Nouncify dashboard to claim ownership, verify the entity, and manage its settings.