API Reference Overview

Base URL

Production: https://api.getbluma.com/api/v1
Development: http://localhost:5001/api/v1

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer bluma_live_your_api_key_here

See Authentication for details.

OpenAPI Specification

The complete API specification is available at:

https://api.getbluma.com/api/v1/openapi.json

Import this into tools like Postman, Insomnia, or Swagger UI for interactive exploration.

API Endpoints

Videos

POST /v1/videos - Generate a new video
GET /v1/videos/:id - Get video status
GET /v1/videos/:id/download - Get download URL

Templates

GET /v1/templates - List all templates
GET /v1/templates/:id - Get template details

Credits

GET /v1/credits/balance - Get credit balance
GET /v1/credits/history - Get transaction history

API Keys

POST /v1/api-keys - Create API key
GET /v1/api-keys - List API keys

Webhooks

POST /v1/webhooks - Register webhook

Usage Analytics

GET /v1/usage/metrics - Get usage metrics

Response Format

All responses are JSON. Successful responses include relevant data:

{
  "id": "batch_abc123",
  "status": "completed",
  ...
}

Error responses follow RFC 7807:

{
  "error": {
    "type": "error_type",
    "title": "Error Title",
    "status": 400,
    "detail": "Detailed error message"
  }
}

See Error Handling for complete details.

Rate Limits

All endpoints are rate limited. Monitor these headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1699127600

See Rate Limits for details.

Pagination

List endpoints support pagination:

GET /v1/credits/history?limit=50&offset=100

Parameter	Type	Description
`limit`	integer	Items per page (max 100)
`offset`	integer	Number of items to skip

Versioning

The API is versioned via the URL path (/v1/). Breaking changes will result in a new version (/v2/). Your existing integrations will continue working.

Support

Documentation: docs.getbluma.com
OpenAPI Spec: /v1/openapi.json
Support: support@getbluma.com

​Base URL

​Authentication

​OpenAPI Specification

​API Endpoints

​Videos

​Templates

​Credits

​API Keys

​Webhooks

​Usage Analytics

​Response Format

​Rate Limits

​Pagination

​Versioning

​Support