Skip to main content

Send message to Insights

POST 
/v2/:media_type/:media_id/insights

Send a message to Insights and receive an AI-generated response about the media's emotional analysis.

Set stream=true (default) to receive the response as Server-Sent Events (SSE) with progressive text chunks. This is the recommended approach as it provides real-time feedback and avoids potential timeout issues with longer responses.

SSE Events:

  • stream_start: Initial event confirming the connection
  • metadata: Contains conversation_id and message_id
  • stream_chunk: Progressive text chunks from AI
  • stream_end: Final event with full_text, token_usage, and credits_charged (flat per-reasoning-mode rate billed for this turn)
  • done: Completion signal
  • error: Error event if processing fails (includes error_id and message). Insufficient-credits failures use error_id: 1402 (matches HTTP 402 in non-streaming mode)

Error Handling in Streaming Mode:

  • Errors that occur before the stream starts (e.g., authentication failures, validation errors) are returned as standard HTTP 4xx/5xx responses with JSON bodies.
  • Errors that occur after the stream has started (e.g., during AI processing) are delivered as SSE error events.

Non-Streaming​

Set stream=false to receive the complete response as JSON. Note: This mode waits for the full AI response before returning, which may result in longer response times or timeouts for complex queries. Use streaming mode for a better experience.

Requirements​

  • Message Length: Maximum 10,000 characters
  • Media Status: Media processing must be completed (status: "completed")
  • Analysis Data: Emotional analysis data must be available. If not yet ready, you'll receive error code 1601 — retry after 30–60 seconds.

Conversation Management​

The system maintains one conversation per user per media item. Your conversation history is preserved across multiple requests — no need to manage conversation IDs manually.

Supported Media Types​

video, audio, image, text

Request​

Responses​

AI response (SSE stream or JSON)