Loading models...

API Reference

AI generation API — image, video, audio, upscale.

Base URL: https://api.example.comAuth: Bearer token

Getting Started

Access all AI generation models through a powerful and easy-to-use HTTP API. Follow the quick start below to make your first request.

Create an API key from your account dashboard. Store it securely (format: bd_xxxxxxxxxxxx).
Call the generation endpoint at /api/v1/{type}/generate with your model_id and parameters.
Receive results via polling /api/v1/generation/{id} or by providing a webhook_url.

Upload Files (Optional)

If a model needs image/video/audio references, upload the file first to obtain a URL.

curl -X POST https://api.example.com/api/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg"

{
  "ok": true,
  "data": {
    "file_id": "c9b7xxxxx",
    "file_name": "c9b7xxxxx.jpg",
    "file_type": "image",
    "file_size": 1024000,
    "content_type": "image/jpeg",
    "file_url": "https://storage.example.com/uploads/c9b7xxxxx.jpg",
    "upload_url": "https://storage.example.com/uploads/c9b7xxxxx.jpg"
  }
}

Tip: use the returned file_url in your model parameters (image, reference_images, reference_videos, etc). Uploaded files are automatically deleted after 1 day.

1. Base URL

All API requests should be made to the following base URL.

https://api.example.com

2. Authentication

All requests must include the Authorization header with your API key.

Authorization: Bearer bd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Error Handling

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

Code	Meaning	Description
400	Bad Request	Invalid or missing parameters.
401	Unauthorized	Invalid API key or not provided.
402	Payment Required	Insufficient credits to complete the request.
404	Not Found	Resource or model not found.
429	Too Many Requests	Rate limit exceeded — retry later.
500	Server Error	Internal server error occurred.

4. Async & Webhooks

Generation is asynchronous and may take 2-5 minutes to complete. You can either poll the status endpoint or receive a webhook when the job finishes.

Status polling

GET  https://api.example.com/api/v1/generation/{generation_id}
Authorization: Bearer YOUR_API_KEY

Status response

{
  "generation_id": "...",
  "status": "processing | completed | failed",
  "type": "image" | "video" | "audio",
  "model": "...",
  "prompt": "...",
  "resultUrl": "...",
  "error": "...",
  "created_at": "2025-11-26T...",
  "completed_at": "2025-11-26T...",
  "aspectRatio": "1:1"
}

Webhook notifications

Provide a webhook_url in the request body to receive an automatic POST when generation completes or fails.

{
  "model_id": "...",
  "parameters": { ... },
  "webhook_url": "https://your-server.com/webhook"
}

Webhook payload

{
  "generation_id": "...",
  "status": "completed" | "failed",
  "type": "image" | "video" | "audio",
  "model": "...",
  "prompt": "...",
  "resultUrl": "...",
  "error": "...",
  "created_at": "2025-11-26T...",
  "completed_at": "2025-11-26T...",
  "aspectRatio": "1:1"
}

5. Check Credits

Check the credit balance of the user who owns the API key. Useful for validating balance before submitting a generation request.

Endpoint

GET  https://api.example.com/api/v1/credits
Authorization: Bearer YOUR_API_KEY

Example request

curl -X GET https://api.example.com/api/v1/credits \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "ok": true,
  "data": {
    "user_id": "clu...xyz",
    "credits": 1234.56,
    "currency": "credits"
  }
}

Tip: check your balance before submitting to avoid failures due to insufficient credits. Each model has a different cost estimate — see the cost field on the /api/v1/models endpoint.

6. Model Pricing

List all available models across every type (image, video, audio, upscale) together with their price in credits. Handy for building pricing pages or estimating cost before generation. This endpoint is public and does not require an API key.

Endpoint

GET  https://api.example.com/api/v1/models/pricing

Query parameters

Name	Type	Description
`type`	string (optional)	Filter by model type. Valid values: `image`, `video`, `audio`, `upscale-image`, `upscale-video`.

Example request

curl -X GET "https://api.example.com/api/v1/models/pricing"

Example request with filter

curl -X GET "https://api.example.com/api/v1/models/pricing?type=image"

Example response

{
  "ok": true,
  "count": 42,
  "currency": "credits",
  "models": [
    {
      "model_id": "black-forest-labs/flux-1.1-pro-ultra",
      "display_name": "FLUX 1.1 [pro] Ultra",
      "description": "High-resolution text-to-image...",
      "category": "Black Forest Labs",
      "status": "active",
      "type": "image",
      "cost": { "default": 0.1 },
      "estimated_time_ms": 10000
    }
  ]
}

Response fields

count — total number of models returned.
currency — always credits.
models[].type — model category (image, video, audio, upscale-image, upscale-video).
models[].cost.default — default cost in credits per generation.
models[].cost.option — optional cost variations based on parameters (if present).
models[].estimated_time_ms — estimated processing time in milliseconds.

Image Models

Generate images from text prompts and optional reference inputs.

Endpoint

curl -X POST https://api.example.com/api/v1/image/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_id": "model_id_here",
    "parameters": {
      "prompt": "Your prompt here"
    }
  }'

No models found.

Video Models

Generate video content from prompts, images, or existing video references.

Endpoint

curl -X POST https://api.example.com/api/v1/video/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_id": "model_id_here",
    "parameters": {
      "prompt": "Your prompt here"
    }
  }'

No models found.

Audio Models

Generate music, speech, and sound effects from text prompts.

Endpoint

curl -X POST https://api.example.com/api/v1/audio/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_id": "model_id_here",
    "parameters": {
      "prompt": "Your prompt here"
    }
  }'

No models found.

Upscale Models — Image

Enhance and upscale images using high-quality AI models.

Endpoint

curl -X POST https://api.example.com/api/v1/upscale/image \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_id": "model_id_here",
    "parameters": {
      "image": "https://storage.example.com/uploads/example.jpg"
    }
  }'

No models found.

Upscale Models — Video

Enhance and upscale videos using high-quality AI models.

Endpoint

curl -X POST https://api.example.com/api/v1/upscale/video \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_id": "model_id_here",
    "parameters": {
      "video": "https://storage.example.com/uploads/example.mp4"
    }
  }'

No models found.