API

The public API is available on Pro and Ultra. Streaming requires Ultra. Base URL: https://api.verba.ink

Get started

Open account Settings → Security → API Keys and create a key. Copy it now; the full value is shown only once.
Copy your Verb’s vanity slug from its profile link.
Call the API from your server, not browser code that exposes the key.

You can use your own private Verbs or available public Verbs. The API applies the selected Verb’s personality and settings.

curl https://api.verba.ink/v1/response \
  -H "Authorization: Bearer YOUR_VERBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "character": "your-verb-slug",
    "messages": [{"role": "user", "content": "Introduce yourself briefly."}]
  }'

Replace both placeholders. Authentication also accepts the x-api-key header.

Chat responses

POST /v1/response

Field	What to send
`character`	Required. A vanity slug, `/v/slug` path, or full Verb profile URL.
`messages`	Required. An array of messages with `role` and `content`.
`session_id`	Optional. Reuse the returned ID to continue the conversation.
`image_urls`	Optional. Accessible HTTP(S) image URLs for vision.
`temperature`, `top_p`, `max_tokens`	Optional generation controls. Omit `max_tokens` to use the model/provider’s default output limit, or set a positive token count. Verba does not clamp it to a plan limit; the provider’s supported limits still apply.
`stream`	Optional. Set to `true` for SSE on Ultra.
`tools`, `tool_choice`, `debug`	Optional. See HTTP tools below.

Use user and assistant messages; custom system messages are not accepted. The Verb’s own instructions supply its character. Read the reply from choices[0].message.content. The response also includes session_id, model, and token usage. For follow-ups, send the new message with the same session_id. Use a different session for each person’s conversation; changing it starts fresh context. Sessions are scoped to the caller and Verb. Message content can be text or an array of text and image parts:

[
  {"type": "text", "text": "Describe this image."},
  {"type": "image_url", "image_url": {"url": "https://example.com/photo.png"}}
]

Streaming

Set "stream": true on /v1/response. Read the text/event-stream response and concatenate choices[0].delta.content from its data: events. The stream ends with data: [DONE]. Handle error events and disconnected requests; don’t assume a partial response is complete. Tool-debug events have a different object type and are not reply text.

Generate an image

POST /v1/image

{
  "character": "your-verb-slug",
  "prompt": "A warm watercolor greenhouse on a rainy rooftop.",
  "size": "1024x1024",
  "response_format": "url",
  "image_urls": ["https://example.com/reference.png"]
}

Only character and prompt are required. Omit image_urls if you don’t need a reference. You may also supply session_id. Image Engine must be enabled for the Verb. The endpoint uses its image settings and the Verb owner’s image allowance and credits. Images are saved in its Gallery. Read the image URL from data[0].url; the response also includes revised_prompt. Only square 1024x1024 output and url format are currently supported.

HTTP tools

Tools let Verba fetch information from an external API before replying. They are request-scoped, not saved on your Verb. Add an OpenAI-style function definition with a function.x_verba_http configuration:

{
  "type": "function",
  "function": {
    "name": "lookup_weather",
    "description": "Look up weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"]
    },
    "x_verba_http": {
      "url": "https://example.com/weather",
      "method": "POST",
      "body_mode": "json"
    }
  }
}

Replace the example URL with your endpoint and put the definition in tools. For a GET lookup, use method: "GET" and query_param to name the query parameter. Optional headers supply API credentials; timeout_ms controls the request timeout, up to 10 seconds. tool_choice accepts "auto" or "none". Use debug: {"tools": true} for execution traces; protect those traces because they may contain request or response details.

Tool arguments are AI-generated. Only expose trusted endpoints with narrowly scoped permissions. Don’t give a tool unrestricted access to payments, deletion, or sensitive data. URLs targeting local or private networks are blocked.

Request limits

Item	Limit
Messages	60 per request; 4,000 characters each; 20,000 characters total
Image URLs	4 combined across message parts and `image_urls`
Image prompt	1,500 characters
Session ID	128 characters; letters, numbers, `:`, `_`, and `-`
Tools	8 definitions; up to 2 executed calls per request

Model, credit, and plan limits also apply. Server rate limits still apply to plans with no monthly message cap.

Handle errors

Error responses include error.type and error.message.

Status	Check
`400`	Required fields, supported options, and request limits.
`401`	Missing, invalid, or revoked API key.
`403`	Plan access, private Verb access, or disabled image generation.
`429`	Rate or allowance limit. Honor `Retry-After` when provided.
`5xx`	Temporary service failure. Retry cautiously; an action may already have occurred.

Revoke exposed keys in Settings. You can keep up to three active API keys. Never publish keys in frontend bundles, repositories, or logs.

Start

Your Verb

Integrations

Build

Help

Get started

Chat responses

Streaming

Generate an image

HTTP tools

Request limits

Handle errors

​Get started

​Chat responses

​Streaming

​Generate an image

​HTTP tools

​Request limits

​Handle errors

Get started

Chat responses

Streaming

Generate an image

HTTP tools

Request limits

Handle errors