API Reference

Complete documentation for integrating Warps Studio into your applications.

Getting Started

The Warps Studio API is organized around REST. Our API accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

Base URL

https://api.warps.studio/v1

Authentication

Authenticate your API requests by including your API key in the Authorization header as a Bearer token. You can manage your API keys from your dashboard.

Authorization: Bearer YOUR_API_KEY

Rate Limits

  • Starter: 60 requests/minute
  • Professional: 300 requests/minute
  • Enterprise: Custom limits (contact sales)

Generate Images

Create new images from text prompts, reference images, or brand kits.

POST /v1/generate

Request Body

Parameter Type Required Description
prompt string Yes Text description of the image to generate (max 2000 characters)
model string No Model ID: warp-v3, warp-v3-turbo, warp-edge. Default: warp-v3
variations integer No Number of variations to generate (1-16). Default: 1
width integer No Image width in pixels (512-2048). Default: 1024
height integer No Image height in pixels (512-2048). Default: 1024
brand_kit_id string No Apply a specific brand kit to the generation
reference_image string No Base64-encoded image or URL for image-to-image generation
style_strength float No Brand style adherence (0.0-1.0). Default: 0.75

Example Request (cURL)

curl https://api.warps.studio/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A modern office workspace with natural lighting",
    "model": "warp-v3-turbo",
    "variations": 4,
    "width": 1024,
    "height": 1024
  }'

Example Request (JavaScript)

const response = await fetch('https://api.warps.studio/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'A modern office workspace with natural lighting',
    model: 'warp-v3-turbo',
    variations: 4,
    width: 1024,
    height: 1024
  })
});

const data = await response.json();
console.log(data);

Example Request (Python)

import requests

response = requests.post(
    'https://api.warps.studio/v1/generate',
    headers={
        'Authorization': f'Bearer {YOUR_API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'prompt': 'A modern office workspace with natural lighting',
        'model': 'warp-v3-turbo',
        'variations': 4,
        'width': 1024,
        'height': 1024
    }
)

data = response.json()
print(data)

Response

{
  "id": "gen_7k3m9n2p4q5r6s8t",
  "status": "processing",
  "model": "warp-v3-turbo",
  "prompt": "A modern office workspace with natural lighting",
  "variations": 4,
  "created_at": "2026-02-17T10:30:00Z",
  "estimated_completion": "2026-02-17T10:30:12Z"
}

Get Generation

Retrieve the status and results of a generation request.

GET /v1/generations/{id}

Path Parameters

Parameter Type Description
id string The generation ID returned from the generate endpoint

Example Request (cURL)

curl https://api.warps.studio/v1/generations/gen_7k3m9n2p4q5r6s8t \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Request (JavaScript)

const response = await fetch(
  'https://api.warps.studio/v1/generations/gen_7k3m9n2p4q5r6s8t',
  {
    headers: {
      'Authorization': `Bearer ${YOUR_API_KEY}`
    }
  }
);

const data = await response.json();
console.log(data);

Example Request (Python)

import requests

response = requests.get(
    'https://api.warps.studio/v1/generations/gen_7k3m9n2p4q5r6s8t',
    headers={'Authorization': f'Bearer {YOUR_API_KEY}'}
)

data = response.json()
print(data)

Response (Completed)

{
  "id": "gen_7k3m9n2p4q5r6s8t",
  "status": "completed",
  "model": "warp-v3-turbo",
  "prompt": "A modern office workspace with natural lighting",
  "variations": 4,
  "created_at": "2026-02-17T10:30:00Z",
  "completed_at": "2026-02-17T10:30:11Z",
  "images": [
    {
      "url": "https://cdn.warps.studio/gen/7k3m9n2p4q5r6s8t/0.png",
      "width": 1024,
      "height": 1024,
      "format": "png"
    },
    {
      "url": "https://cdn.warps.studio/gen/7k3m9n2p4q5r6s8t/1.png",
      "width": 1024,
      "height": 1024,
      "format": "png"
    },
    {
      "url": "https://cdn.warps.studio/gen/7k3m9n2p4q5r6s8t/2.png",
      "width": 1024,
      "height": 1024,
      "format": "png"
    },
    {
      "url": "https://cdn.warps.studio/gen/7k3m9n2p4q5r6s8t/3.png",
      "width": 1024,
      "height": 1024,
      "format": "png"
    }
  ]
}

Create Brand Kit

Upload a brand kit with logos, colors, fonts, and style references for consistent generations.

POST /v1/brand-kits

Request Body

Parameter Type Required Description
name string Yes Name of the brand kit
logo string No Base64-encoded logo image or URL
colors array No Array of hex color codes (e.g., ["#FF5733", "#3498DB"])
style_references array No Array of base64-encoded reference images or URLs
description string No Text description of brand style and aesthetics

Example Request (cURL)

curl https://api.warps.studio/v1/brand-kits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp Brand",
    "colors": ["#FF5733", "#3498DB", "#2ECC71"],
    "description": "Modern, clean design with bold colors and geometric shapes"
  }'

Example Request (JavaScript)

const response = await fetch('https://api.warps.studio/v1/brand-kits', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corp Brand',
    colors: ['#FF5733', '#3498DB', '#2ECC71'],
    description: 'Modern, clean design with bold colors and geometric shapes'
  })
});

const data = await response.json();
console.log(data);

Example Request (Python)

import requests

response = requests.post(
    'https://api.warps.studio/v1/brand-kits',
    headers={
        'Authorization': f'Bearer {YOUR_API_KEY}',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Acme Corp Brand',
        'colors': ['#FF5733', '#3498DB', '#2ECC71'],
        'description': 'Modern, clean design with bold colors and geometric shapes'
    }
)

data = response.json()
print(data)

Response

{
  "id": "bk_2n3p4q5r6s8t9u0v",
  "name": "Acme Corp Brand",
  "colors": ["#FF5733", "#3498DB", "#2ECC71"],
  "description": "Modern, clean design with bold colors and geometric shapes",
  "created_at": "2026-02-17T10:35:00Z"
}

List Models

Get information about available generation models and their capabilities.

GET /v1/models

Example Request (cURL)

curl https://api.warps.studio/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Request (JavaScript)

const response = await fetch('https://api.warps.studio/v1/models', {
  headers: {
    'Authorization': `Bearer ${YOUR_API_KEY}`
  }
});

const data = await response.json();
console.log(data);

Example Request (Python)

import requests

response = requests.get(
    'https://api.warps.studio/v1/models',
    headers={'Authorization': f'Bearer {YOUR_API_KEY}'}
)

data = response.json()
print(data)

Response

{
  "models": [
    {
      "id": "warp-v3",
      "name": "Warp-V3",
      "description": "Our flagship model with industry-leading brand consistency",
      "max_resolution": 2048,
      "avg_generation_time": 11.5,
      "capabilities": ["text-to-image", "image-to-image", "inpainting", "outpainting"]
    },
    {
      "id": "warp-v3-turbo",
      "name": "Warp-V3 Turbo",
      "description": "5x faster inference while maintaining quality",
      "max_resolution": 2048,
      "avg_generation_time": 2.3,
      "capabilities": ["text-to-image", "image-to-image"]
    },
    {
      "id": "warp-edge",
      "name": "Warp-Edge",
      "description": "Optimized for speed and efficiency on edge devices",
      "max_resolution": 1024,
      "avg_generation_time": 0.8,
      "capabilities": ["text-to-image"]
    }
  ]
}

Error Codes

The API uses standard HTTP status codes to indicate success or failure:

Code Description
200 Success - Request completed successfully
400 Bad Request - Invalid parameters or malformed request
401 Unauthorized - Invalid or missing API key
402 Payment Required - Insufficient credits or expired subscription
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Something went wrong on our end
503 Service Unavailable - Temporary service disruption

Error Response Format

{
  "error": {
    "code": "invalid_parameters",
    "message": "Width must be between 512 and 2048 pixels",
    "param": "width",
    "type": "invalid_request_error"
  }
}

Need Help?

Check out our comprehensive documentation or reach out to our developer support team.