API Documentation

Welcome to the Melancholy AI API. Build powerful applications using our state-of-the-art models for text, image, and video generation.

Overview

The Melancholy AI API provides a unified interface to access multiple leading AI models, including OpenAI's GPT, Anthropic's Claude, Google's Gemini, xAI's Grok, Mistral, Meta Llama, and more.

Our API follows standard REST principles and returns JSON-encoded responses. It is designed to be highly compatible with existing OpenAI SDKs to make migration as seamless as possible.

Rate Limits & Plans

API usage is subject to the following rate limits depending on your active plan. Exceeding these limits will result in a 429 Too Many Requests error.

Plan	Rate Limit	Cooldown	Context (Max Prompts)	Max Tokens	Models
Free	50 / day	10 sec	8,000 chars	1,024	GPT-3.5, Claude Haiku
Trial	500 / hour	5 sec	20,000 chars	4,096	All Models
2-Week & Monthly	750 / hour	3 sec	80,000 chars	32,768	All Models

* When your plan expires, your account is automatically downgraded to the Free tier until renewed.

Base URL

All API requests should be made relative to the following base URL:

https://app.melancholyai.fun/api/v1/

Getting Started

Follow these quick steps to obtain your API key and make your first request.

1. Create an Account

First, you need to sign up for a Melancholy AI account. Once registered and logged in, you will have access to the developer dashboard.

2. Generate an API Key

Navigate to the API Keys section in your dashboard. Click on "Create API Key". Your new key will begin with sk-. Keep this key secure and never expose it in client-side code (like frontend JavaScript).

3. Choose a Subscription Plan

All new accounts get access to the Free tier, which includes a daily limit of 50 requests using our base models. To access premium models like GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro, you will need to upgrade to the Trial, 2-Week, or Monthly plan from the billing section.

4. Make Your First Request

Now you're ready to use the API! Here's a quick example using curl to verify everything is working:

BASH

curl https://app.melancholyai.fun/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Say hello!"}]
  }'

Authentication

Learn how to authenticate your API requests.

Bearer Token

The Melancholy API uses Bearer Tokens for authentication. You can find your API key in the API Key section of your dashboard.

You must include your API key in the Authorization header of every request.

HTTP

Authorization: Bearer YOUR_API_KEY

Chat Completions

Generate text and converse with cutting-edge models.

Create chat completion

Creates a model response for the given chat conversation.

POST /chat/completions

Request Body

Parameter	Type	Description
model Required	string	ID of the model to use (e.g., `gpt-4o`, `qwen3-max`). See your dashboard for the full list of supported models.
messages Required	array	A list of messages comprising the conversation so far. Each item should have a `role` (e.g., system, user, assistant) and `content`.
stream	boolean	If set, partial message deltas will be sent in Server-Sent Events (SSE). Defaults to false.

Standard Request Example (Python)

Python

import requests

response = requests.post(
    url="https://app.melancholyai.fun/api/v1/chat/completions/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "qwen3-max",
        "messages": [
            {"role": "user", "content": "Hello, how are you?"}
        ]
    }
)

print(response.json())

Streaming Request Example (Python)

For building real-time UI applications, enable streaming to receive tokens as they are generated.

Python

import requests

response = requests.post(
    url="https://app.melancholyai.fun/api/v1/chat/completions/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "model": "qwen3-max",
        "messages": [
            {"role": "user", "content": "Write a short poem."}
        ],
        "stream": True
    },
    stream=True
)

for chunk in response.iter_lines():
    if chunk:
        print(chunk.decode('utf-8'))

Image Generation

Create images from text prompts using DALL-E 3, Flux, and more.

Create Image

Creates an image given a prompt.

POST /images/generations

Request Example (Python)

Python

import requests

response = requests.post(
  url="https://app.melancholyai.fun/api/v1/images/generations/",
  headers={
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "User-Agent": "MelancholyAI-Client" 
  },
  json={
    "prompt": "A futuristic city at sunset with flying cars",
    "n": 1,
    "model": "flux",
    "size": "1024x1024"
  }
)

print(response.json())

Video Generation

Generate high-quality videos using models like Google Veo.

Create Video Task

Video generation is fully asynchronous. You first submit a task, which returns a Task ID. You then poll the status of this task until it is completed.

POST /video/generations

Create Task Example (Python)

Python

import requests

response = requests.post(
  url="https://app.melancholyai.fun/api/v1/video/generations/",
  headers={
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "User-Agent": "MelancholyAI-Client" 
  },
  json={
    "model": "google/veo-3-1-fast",
    "input": {
        "prompt": "A drone shot flying over a tropical beach with crystal clear water",
        "aspect_ratio": "LANDSCAPE",
        "video_generate_type": "text_to_video"
    }
  }
)

print(response.json())
# Will return: { "task_id": "YOUR_TASK_ID" }

Check Task Status

Use the Task ID obtained from the previous request to poll the status.

GET /video/generations/{task_id}

Check Status Example (Python)

Python

import requests
import time

task_id = "YOUR_TASK_ID"

while True:
    response = requests.get(
        url=f"https://app.melancholyai.fun/api/v1/video/generations/{task_id}",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
            "User-Agent": "MelancholyAI-Client"
        }
    )
    
    data = response.json()
    status = data.get("status")
    
    if status == "COMPLETED":
        print("Video generated successfully!")
        print("Video URL:", data.get("video_url"))
        break
    elif status == "FAILED":
        print("Generation failed:", data.get("error"))
        break
        
    print(f"Status: {status}... checking again in 5 seconds")
    time.sleep(5)