API Reference

Complete API documentation

Base URL

https://api.arcada.dev

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Health Check

Verify API connectivity and authentication.

GET/api/v1/health

Response

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "version": "1.0.0"
}

Content Generation

Generate content using universal Router format API. Automatically selects the top-ranked model from DesignArena's leaderboard for your format. Compatible with standard SDKs for easy integration.

POST/api/v1/generate

Request

Required fields: messages, input_format, output_format

{
  // Required: Category selection - determines which DesignArena arena to use
  "input_format": "text",  // Required - input type: "text" | "image" | "video" | "audio"
  "output_format": "website",  // Required - output type (see available formats below)
  
  // Required: Messages array - at least one user message required
  "messages": [
    {
      "role": "system",  // Optional: system message for context
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",  // Required: at least one user message
      "content": "Create a landing page for a coffee shop",
      "image_url": "https://..."  // Optional: for vision models (can be string URL or object: { "url": "https://..." })
    }
  ],
  
  // Optional: Multimodal input fields (for image-to-image, video-to-video, speech-to-speech/text)
  "input_image": "data:image/png;base64,...",  // Optional: base64 or URL for image-to-image (required if input_format="image" and output_format="image")
  "input_video": "https://...",  // Optional: URL for video-to-video (required if input_format="video" and output_format="video" or "video-to-video")
  "input_audio": "data:audio/mp3;base64,...",  // Optional: base64 or URL for speech-to-speech/text (required if input_format="audio" and output_format="speech"|"sts"|"text"|"stt")
  
  // Optional: Generation parameters
  "temperature": 0.7,  // Optional: 0-2, controls randomness (default: 0.7)
  "max_tokens": 2000,  // Optional: maximum tokens in response
  "top_p": 1.0,  // Optional: 0-1, nucleus sampling parameter
  "frequency_penalty": 0.0,  // Optional: -2 to 2, reduces repetition
  "presence_penalty": 0.0,  // Optional: -2 to 2, encourages new topics
  "stream": false,  // Optional: streaming responses (currently not supported)
  
  // Optional: Arcada-specific fields
  "system_prompt": "...",  // Optional: custom system prompt (overrides DesignArena's default system prompt for the category)
  "images": ["url1", "url2"],  // Optional: additional image URLs/base64 for vision models
  "code_context": "..."  // Optional: code context for code generation (max 50000 characters)
}

Note: The model field is not used. Arcada automatically selects the top-performing model from DesignArena's leaderboard based on your input_format and output_format.

System Prompts: By default, Arcada uses DesignArena's category-specific system prompts. You can override this by providing a system_prompt field in your request.

Available Input Formats

text - Text input (default, used for most generation types)
image - Image input (for image-to-image transformation)
video - Video input (for video-to-video transformation)
audio - Audio input (for speech-to-speech and speech-to-text)

Available Output Formats

Supported output formats:

website - HTML website generation
image - Image generation
logo - Logo design
svg - SVG graphics
video - Video generation
video-to-video - Video-to-video transformation
image-to-image - Image-to-image transformation
slides - Presentation slides
conversation - Conversational AI
tts - Text-to-Speech
sts - Speech-to-Speech
stt - Speech-to-Text
music - Music generation
gamedev - Game development assets
dataviz - Data visualization
3d - 3D design
uicomponent - UI component code
graphic design - Graphic design

Response

Standard Router format response compatible with OpenAI SDK and other standard SDKs.

{
  // Standard Router format fields
  "id": "chatcmpl-abc123...",  // Unique request ID
  "object": "chat.completion",  // Always "chat.completion"
  "created": 1234567890,  // Unix timestamp
  "model": "GPT-4 Turbo",  // Model name used (automatically selected from DesignArena leaderboard)
  
  // Response choices
  "choices": [
    {
      "index": 0,  // Always 0 for single response
      "message": {
        "role": "assistant",  // Always "assistant"
        "content": "Generated content here...",  // Main content (text/HTML/code)
        "image_url": "https://...",  // Optional: for image generation (data URL or regular URL)
        "video_url": "https://..."   // Optional: for video generation
      },
      "finish_reason": "stop"  // "stop" | "length" | "content_filter" | null
    }
  ],
  
  // Token usage information
  "usage": {
    "prompt_tokens": 150,  // Input tokens (estimated if provider doesn't return)
    "completion_tokens": 200,  // Output tokens (estimated for media generation)
    "total_tokens": 350  // Total tokens
  },
  
  // Optional: System fingerprint (not currently used)
  "system_fingerprint": null
}

Response Format by Output Type

Website Generation

{
  "choices": [{
    "message": {
      "content": "<html>...</html>",  // Full HTML content
      "role": "assistant"
    }
  }]
}

Image Generation

{
  "choices": [{
    "message": {
      "content": "Media generated successfully.",  // Fallback text
      "image_url": "data:image/png;base64,...",  // Image URL (data URL or regular URL)
      "role": "assistant"
    }
  }],
  "usage": {
    "prompt_tokens": 50,  // Estimated if provider doesn't return
    "completion_tokens": 100,  // Estimated for image generation
    "total_tokens": 150
  }
}

Video Generation

{
  "choices": [{
    "message": {
      "content": "Media generated successfully.",  // Fallback text
      "video_url": "https://...",  // Video URL
      "role": "assistant"
    }
  }],
  "usage": {
    "prompt_tokens": 50,  // Estimated if provider doesn't return
    "completion_tokens": 100,  // Estimated for video generation
    "total_tokens": 150
  }
}

Error Response

{
  "error": {
    "message": "Error description here",
    "type": "invalid_request_error" | "rate_limit_error" | "insufficient_quota" | "server_error",
    "code": "invalid_api_key" | "rate_limit_exceeded" | "insufficient_credits" | "internal_error" | null
  }
}

Rate Limits

300 requests per minute
10,000 requests per hour
100,000 requests per day