Cerebraform - Generative AI APIs for Developers

Rate Limits

To ensure fair usage and system stability, our APIs are subject to rate limits. Limits are applied based on your account type (Free or Paid). Exceeding these limits will result in a `429 Too Many Requests` error.

When you are rate-limited, the response will include a `Retry-After` header indicating how many seconds to wait before making a new request.

Limits by Account Tier

API/Operation	Free Tier Limit	Paid Tier Limit
Task Creation (Image/Video)	10 per hour	200 per hour
Status Polling	20 per minute	120 per minute
Anonymous / No API Key	200 per day (global)

Example Rate Limit Response


HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 52

{
  "code": 429,
  "error": "too_many_requests",
  "msg": "Rate limit exceeded. Try again in 52 seconds.",
  "retry_after": 52
}

Image Generation

Generates an image based on a text prompt and an optional initial image. This is an asynchronous task.

Workflow in 3 Steps

Submit Task: Send a `POST` request to `/ai/v1/to-image` with your parameters. The API will immediately return a `request_id`.
Poll for Status: Periodically send a `GET` request to `/ai/v1/to-image/status/{request_id}` to check the task's progress.
Fetch Result: Once the task status is `done` (status code 2), send a `GET` request to `/ai/v1/to-image/result/{request_id}` to get the image URL(s). If the status becomes `failed` (status code -1), the task has terminated due to an error.

Endpoints

POST /ai/v1/to-image

Submits a new image generation task.

Body Parameters:

prompt	String	Required	The text description of the desired image. (Max 1000 characters)
image_url	String	Optional	URL of an initial image for image-to-image tasks.
aspect_ratio	String	Optional	e.g., "9:16", "1:1". Defaults to "9:16".

GET /ai/v1/to-image/status/{request_id}

GET /ai/v1/to-image/result/{request_id}


import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://cerebraform.com" 

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Step 1: Submit Task
payload = {
    "prompt": "a cinematic photo of a cat wearing a wizard hat",
    "aspect_ratio": "1:1"
}
submit_url = f"{BASE_URL}/ai/v1/to-image"
submit_res = requests.post(submit_url, json=payload, headers=headers)

if submit_res.status_code != 201:
    print(f"Error submitting task: {submit_res.text}")
    exit()

request_id = submit_res.json()['request_id']
print(f"Task submitted with request_id: {request_id}")

# Step 2: Poll for Status
status_url = f"{BASE_URL}/ai/v1/to-image/status/{request_id}"
while True:
    status_res = requests.get(status_url, headers=headers)
    status_data = status_res.json()
    status = status_data.get('status')
    
    print(f"Current status: {status_data.get('message', 'checking...')}")

    if status == 2: # Status 'done'
        break
    elif status == -1: # Status 'failed'
        print("Task failed. Check the message for details.")
        exit()
        
    time.sleep(5) # Wait 5 seconds before polling again

# Step 3: Fetch Result
result_url = f"{BASE_URL}/ai/v1/to-image/result/{request_id}"
result_res = requests.get(result_url, headers=headers)
result_data = result_res.json()

print("\nTask finished! Results:")
for result in result_data.get('results', []):
    print(result['url'])


# Step 1: Submit Task
# Replace with your domain and API key
REQUEST_ID=$(curl -s -X POST "https://cerebraform.com/ai/v1/to-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cinematic photo of a cat wearing a wizard hat",
    "aspect_ratio": "1:1"
  }' | jq -r .request_id)

echo "Task submitted, request_id: $REQUEST_ID"

# Step 2: Poll for Status (run this command periodically)
echo "Polling status..."
curl -s -X GET "https://cerebraform.com/ai/v1/to-image/status/$REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq

# Step 3: Fetch Result (run when status is '2' (done))
echo "Fetching result..."
curl -s -X GET "https://cerebraform.com/ai/v1/to-image/result/$REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq

Video Generation

Generates a short video clip based on a text prompt and an optional initial image. This is an asynchronous task.

Workflow in 3 Steps

Submit Task: Send a `POST` request to `/ai/v1/to-video` with your parameters. The API will immediately return a `request_id`.
Poll for Status: Periodically send a `GET` request to `/ai/v1/to-video/status/{request_id}` to check the task's progress.
Fetch Result: Once the task status is `done` (status code 2), send a `GET` request to `/ai/v1/to-video/result/{request_id}` to get the video URL. If the status becomes `failed` (status code -1), the task has terminated due to an error.

Endpoints

POST /ai/v1/to-video

Submits a new video generation task.

Body Parameters:

prompt	String	Required	The text description of the desired video. (Max 1000 characters)
image_url	String	Optional	URL of an initial image to animate.
aspect_ratio	String	Optional	e.g., "9:16", "16:9". Defaults to "9:16".
duration	Integer	Optional	Video duration in seconds. Valid options are `5` or `10`. Defaults to `5` if omitted or an invalid value is provided.

GET /ai/v1/to-video/status/{request_id}

GET /ai/v1/to-video/result/{request_id}


# The process is identical to image generation, just use the /to-video endpoints.
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://cerebraform.com"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Step 1: Submit Task
payload = {
    "prompt": "a peaceful river flowing through a dense forest, 4k, cinematic",
    "duration": 10
}
submit_url = f"{BASE_URL}/ai/v1/to-video"
submit_res = requests.post(submit_url, json=payload, headers=headers)
request_id = submit_res.json()['request_id']
print(f"Video task submitted with ID: {request_id}")

# Step 2: Poll for Status
status_url = f"{BASE_URL}/ai/v1/to-video/status/{request_id}"
while True:
    status_res = requests.get(status_url, headers=headers)
    status_data = status_res.json()
    status = status_data.get('status')
    
    print(f"Current status: {status_data.get('message', 'checking...')}")
    
    if status == 2: break
    if status == -1:
        print("Video task failed. Check the message for details.")
        exit()
    time.sleep(10) # Video may take longer, poll less frequently

# Step 3: Fetch Result
result_url = f"{BASE_URL}/ai/v1/to-video/result/{request_id}"
result_res = requests.get(result_url, headers=headers)
print("\nVideo ready! Result:")
print(result_res.json())


# Step 1: Submit Task
REQUEST_ID=$(curl -s -X POST "https://cerebraform.com/ai/v1/to-video" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a peaceful river flowing through a dense forest, 4k, cinematic",
    "duration": 10
  }' | jq -r .request_id)

echo "Video task submitted, request_id: $REQUEST_ID"

# Step 2: Poll for Status (run this command periodically)
curl -s "https://cerebraform.com/ai/v1/to-video/status/$REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq

# Step 3: Fetch Result (when status is '2' (done))
curl -s "https://cerebraform.com/ai/v1/to-video/result/$REQUEST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" | jq

Query Credits

Fetches the current credit balance for your account.

Endpoint

GET /ai/v1/user/credits

Returns the integer value of your available credits.

Example Response


{
  "credits": 450
}


import requests

API_KEY = "YOUR_API_KEY"
url = "https://cerebraform.com/ai/v1/user/credits"
headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.get(url, headers=headers)
print(response.json())
# Expected Output: {'credits': 450}


curl -X GET "https://cerebraform.com/ai/v1/user/credits" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cerebraform: Generative AI for Developers

API Reference

Authentication

Rate Limits

Limits by Account Tier

Example Rate Limit Response

Image Generation

Workflow in 3 Steps

Endpoints

Video Generation

Workflow in 3 Steps

Endpoints

Query Credits

Endpoint

Example Response