Skip to main content
API docs by Redocly

Wallboard API - AI (2.0)

Generate text, structured responses, images and speech, or transcribe audio for the selected customer. These endpoints require at least VIEWER access and use the customer's AI credentials and budget policy. Available features depend on the server version.

Responses and conversations

Send input to /api/ai/responses; use outputFormat for text or JSON-schema output. Requests are stateless unless you supply an application-owned sessionId. Reuse that ID to continue a conversation; sessions are scoped to the customer and current user. Expired session mappings start a new conversation. Avoid concurrent calls with the same session ID: the last completed state write wins.

Provider and model selection are server configuration. Provider-specific request fields are rejected. Use outputText or outputJson in the response rather than depending on provider-specific rawOutput.

Application-executed tools

  1. Send sessionId, input and your function tools.
  2. When the response has status=requires_action, execute the returned toolCalls in your application.
  3. Continue with the same sessionId and tools, supplying all corresponding toolResults together. Each result identifies its callId and contains the function output; input may then be omitted.
  4. Repeat until status=completed.

Wallboard does not execute these functions. Your application controls which tools may run and their permissions. Only custom function tools are supported; provider built-in tools are not accepted.

Streaming and media

/api/ai/responses/stream uses server-sent events: output_text_delta carries text updates; completed carries the result, tool calls, session ID and usage. After streaming starts, handle failures through the SSE error event as well as HTTP errors before the stream starts.

Image results support base64 or provider-hosted URLs; persist base64 results when you need durable image data. Speech generation returns base64 audio with its content type. Transcription accepts an audio file as multipart data. Voice listing is free. Paid calls check the customer budget before execution and record returned usage afterward. usage.billableTokens represents quota-equivalent units; use usage.cost for the returned USD cost and estimate flag.

ai

Generate a response

Minimum role: VIEWER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
instructions
string
input
any
temperature
number <double>
topP
number <double>
maxOutputTokens
integer <int32>
object (AiOutputFormat)

schema must be nonempty for json_schema.

object
sessionId
string
reasoningEffort
string
Enum: "low" "medium" "high"
Array of objects (AiFunctionToolDefinition)
object (AiToolChoice)
Array of objects (AiToolResult)

Responses

Request samples

Content type
application/json
{
  • "input": "Write a short welcome message."
}

Response samples

Content type
application/json
{
  • "outputText": "string",
  • "outputJson": null,
  • "rawOutput": null,
  • "status": "completed",
  • "sessionId": "string",
  • "toolCalls": [
    ],
  • "usage": {
    },
  • "durationMs": 0
}

Generate images

Minimum role: VIEWER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
prompt
required
string
count
integer <int32> [ 1 .. 10 ]
Default: 1
responseFormat
string
Enum: "base64" "url"
quality
string
Enum: "low" "medium"
resolution
string
Enum: "1k" "2k"
aspectRatio
string
Enum: "auto" "1:1" "16:9" "9:16" "4:3" "3:4" "3:2" "2:3" "2:1" "1:2" "19.5:9" "9:19.5" "20:9" "9:20"

Responses

Request samples

Content type
application/json
{
  • "prompt": "A calm blue abstract background",
  • "count": 1
}

Response samples

Content type
application/json
{
  • "images": [
    ],
  • "usage": {
    },
  • "durationMs": 0
}

Generate speech

Minimum role: VIEWER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
text
required
string <= 15000 characters
voice
string
language
string
format
string
Enum: "mp3" "wav" "pcm" "mulaw" "alaw"
sampleRate
integer <int32>
bitRate
integer <int32>
speed
number <double>
textNormalization
boolean

Responses

Request samples

Content type
application/json
{
  • "text": "Welcome to our reception."
}

Response samples

Content type
application/json
{
  • "base64Audio": "string",
  • "contentType": "string",
  • "inputCharacters": 0,
  • "usage": {
    },
  • "durationMs": 0
}

Stream a response

Streams output_text_delta events followed by a completed result with status, sessionId, toolCalls and usage. Use the response and tool workflow described above. After headers are sent, failures arrive as SSE error events.

Minimum role: VIEWER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
instructions
string
input
any
temperature
number <double>
topP
number <double>
maxOutputTokens
integer <int32>
object (AiOutputFormat)

schema must be nonempty for json_schema.

object
sessionId
string
reasoningEffort
string
Enum: "low" "medium" "high"
Array of objects (AiFunctionToolDefinition)
object (AiToolChoice)
Array of objects (AiToolResult)

Responses

Request samples

Content type
application/json
{
  • "input": "Write a short welcome message."
}

List voices

Minimum role: VIEWER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Responses

Response samples

Content type
application/json
{
  • "voices": [
    ]
}

Transcribe audio

Minimum role: VIEWER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: multipart/form-data
required
file
required
string <binary>
language
string
diarize
boolean
multichannel
boolean
channels
integer [ 2 .. 8 ]
fillerWords
boolean
keyterms
Array of strings

Responses

Response samples

Content type
application/json
{
  • "text": "string",
  • "language": "string",
  • "durationSeconds": 0.1,
  • "words": null,
  • "channels": null,
  • "usage": {
    },
  • "durationMs": 0
}