Skip to main content

AI overview

Use the AI API to add generation, search, and voice capabilities to your application without building a workflow for each request. Calls use the services available to your Intellectible project.

Choose a capability​

EndpointUse it forResponse
Chat completionsGenerate responses, request structured JSON, or ask the model to select function tools.JSON, or streamed chat chunks.
EmbeddingsRepresent text as vectors for semantic search and similarity.One vector per input.
RerankingScore a set of candidate passages against a query.One score per candidate, in input order.
Speech synthesisTurn text into spoken audio.Audio bytes.
TranscriptionTurn a recording into text.Transcript and audio metadata.

A search application might embed its documents, retrieve candidate passages for a query, rerank them, and supply the strongest passages to a chat request. These are separate operations: the API does not automatically search your Library or databases when you ask a question.

Model tiers​

Chat requests use the public tier names small, medium, and large, rather than underlying model identifiers.

  • Small: a starting point for straightforward, focused tasks.
  • Medium: a starting point for general-purpose generation and analysis.
  • Large: consider for more demanding tasks where quality matters more than response speed.

Evaluate tiers with representative inputs. Latency and output quality depend on the task, input size, reasoning settings, and project configuration; tier names are not guarantees of a particular response time.

The project's model policy is applied automatically. Your request and response still use the public tier name. Embeddings, reranking, and audio endpoints do not expose tier selection.

Authentication and permissions​

Send the full project key in Authorization, without Bearer. Permissions are independent:

CapabilityRequired permission
Chatllm.complete on the requested tier, or all tiers.
Embeddingsembeddings.create.
Rerankingrerank.create.
Speech synthesisspeech.synthesize.
Transcriptionspeech.transcribe.

All requests target :projectid. Examples use the base URL and environment variables from the Quickstart. Keep keys in trusted server-side code.

Chat features​

Chat completions support:

  • Conversation history supplied in messages.
  • A generated-token budget and sampling temperature.
  • Per-request reasoning_effort.
  • Function tools that your application validates and executes.
  • JSON-object or JSON-schema output.
  • Streaming responses, including tool-call fragments.

Each request is independent: send the relevant conversation history when continuing a conversation. These endpoints do not create an agent session, execute tools for you, or automatically grant access to project files.

Use only the fields documented for the endpoint. Familiar request shapes do not imply support for every option offered by other AI APIs.

Responses and reliability​

For non-streaming chat, inspect choices and finish_reason, not a workflow-style success field. Generated content may be incomplete, incorrect, or require validation before use.

For streaming chat, check for error events and the final [DONE] marker; HTTP 200 alone is not proof of a successful generation. Audio synthesis returns bytes, so do not parse its successful body as JSON.

Requests are subject to project/key rate limits and service limits. Handle 429 responses with backoff, and remember that retrying a generation can produce a different answer and additional usage. See Errors, limits and retries.