For AI Agents

# Arcada Gateway API Documentation ## Base URL https://api.arcada.dev ## Authentication All API requests require authentication using an API key. Include your API key in the Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` ## Endpoints ### Health Check Verify API connectivity and authentication status. **Endpoint:** `GET /api/v1/health` **Headers:** - `Authorization: Bearer YOUR_API_KEY` **Response:** ```json { "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. **Endpoint:** `POST /api/v1/generate` **Headers:** - `Authorization: Bearer YOUR_API_KEY` - `Content-Type: application/json` **Request Body:** ```json { "input_format": "text", "output_format": "website", "messages": [ { "role": "user", "content": "Create a landing page for a coffee shop" } ] } ``` **Required Fields:** - `input_format` (string): Input type - "text" | "image" | "video" | "audio" - `output_format` (string): Output type (see available formats below) - `messages` (array): At least one message with role "user" required **Optional Fields:** - `input_image` (string): Base64 or URL for image-to-image (required if input_format="image" and output_format="image") - `input_video` (string): URL for video-to-video (required if input_format="video" and output_format="video" or "video-to-video") - `input_audio` (string): Base64 or URL for speech-to-speech/text (required if input_format="audio" and output_format="speech"|"sts"|"text"|"stt") - `temperature` (number): 0-2, controls randomness (default: 0.7) - `max_tokens` (number): Maximum tokens in response - `system_prompt` (string): Custom system prompt (overrides DesignArena's default) - `images` (array): Additional image URLs/base64 for vision models - `code_context` (string): Code context for code generation (max 50000 characters) **Response:** ```json { "id": "chatcmpl-abc123...", "object": "chat.completion", "created": 1234567890, "model": "GPT-4 Turbo", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Generated content here...", "image_url": "https://...", "video_url": "https://..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 150, "completion_tokens": 200, "total_tokens": 350 } } ``` **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`. ## Available Formats ### 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) ### 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 ## Rate Limits - 300 requests per minute - 10,000 requests per hour - 100,000 requests per day ## Error Handling All errors follow a consistent format: ```json { "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 } } ``` **HTTP Status Codes:** - `400 Bad Request` - Invalid parameters or missing required fields - `401 Unauthorized` - Missing or invalid API key - `402 Payment Required` - Insufficient credits - `429 Too Many Requests` - Rate limit exceeded - `500 Internal Server Error` - Server-side error ## Example Requests ### Health Check ```bash curl https://api.arcada.dev/api/v1/health \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Content Generation ```bash curl https://api.arcada.dev/api/v1/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_format": "text", "output_format": "website", "messages": [ { "role": "user", "content": "Create a landing page for a coffee shop" } ] }' ``` ### Image-to-Image ```bash curl https://api.arcada.dev/api/v1/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_format": "image", "output_format": "image", "messages": [ { "role": "user", "content": "Transform this into a watercolor painting" } ], "input_image": "data:image/jpeg;base64,..." }' ``` ## Getting an API Key To get an API key, create a developer account at https://api.arcada.dev and generate an API key from your dashboard. ## Additional Resources - Quickstart Guide: https://api.arcada.dev/docs/quickstart - Complete API Reference: https://api.arcada.dev/docs/reference