API Documentation

The Amarsia API allows you to interact with your deployed workflows programmatically. You can send text, images, videos, and audio files for multimodal AI processing.

We offer two types of APIs: Standard API for complete responses and Streaming API for real-time word-by-word responses.

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-api-key: YOUR_API_KEY

Get your API key from Settings → API Keys in your dashboard.

Standard API

Recommended

Returns complete responses with token usage information. Perfect for most use cases including automation, integrations, and batch processing.

POST

/v1/runner/{deployment_id}

curl https://api.amarsia.com/v1/runner/YOUR_DEPLOYMENT_ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "content": [{
      "type": "text",
      "text": "Your input message here."
    }]
  }'

Response

{
  "content": "Your AI-generated response here...",
  "model": "deepseek-chat",
  "output_tokens": 123,
  "input_tokens": 456
}

Streaming API

Receive responses word-by-word in real-time. Perfect for chat interfaces and interactive applications where you want to display results as they generate.

POST

/v1/runner/{deployment_id}/stream

async function streamResponse(prompt) {
  const response = await fetch(
    'https://api.amarsia.com/v1/runner/YOUR_DEPLOYMENT_ID/stream',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY',
      },
      body: JSON.stringify({
        content: [{ type: 'text', text: prompt }]
      })
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value, { stream: true });
    console.log(chunk); // Display in real-time
  }
}

Key Points

• Response streams as plain text (no JSON parsing needed)
• Spacing and line breaks are already formatted
• Just concatenate chunks as they arrive
• Token counts are not available in streaming mode

Multimodal Requests

Send multiple types of content in a single request. Both standard and streaming APIs support multimodal input.

{
  "content": [
    {
      "type": "text",
      "text": "Analyze this image and video."
    },
    {
      "type": "image",
      "mime_type": "image/jpeg",
      "file_uri": "https://example.com/image.jpg"
    },
    {
      "type": "video",
      "mime_type": "video/mp4",
      "file_uri": "https://example.com/video.mp4"
    }
  ]
}

Content Types

Supported content types for multimodal processing.

Text

{
  "type": "text",
  "text": "Your text content here"
}

Image

{
  "type": "image",
  "mime_type": "image/jpeg",
  "file_uri": "https://example.com/image.jpg"
}

Video

{
  "type": "video",
  "mime_type": "video/mp4",
  "file_uri": "https://example.com/video.mp4"
}

Audio

{
  "type": "audio",
  "mime_type": "audio/mp3",
  "file_uri": "https://example.com/audio.mp3"
}

PDF / Documents

{
  "type": "url",
  "mime_type": "application/pdf",
  "file_uri": "https://example.com/document.pdf"
}