Skip to main content
Every method maps directly to a REST endpoint. The route is shown above each example so you can use cURL or any HTTP client if you prefer.

​
API

​
API status

Verify your API key connection and get key metadata. GET /v1/status
TypeScript
const res = await client.status();

console.log(res.data.account_id);
console.log(res.data.apikey_id);
console.log(res.data.apikey_prefix);
console.log(res.data.apikey_name);
console.log(res.data.apikey_created_at);
console.log(res.data.apikey_last_used_at);
console.log(res.data.apikey_expires_at);

​
API usage

Get aggregated usage analytics for a lookback window of 1-90 days (default 30). Returns your current credit balance, total request and generation counts, per-endpoint breakdowns (total, success, 4xx, 5xx, error code distribution), and per-provider cost summaries (submissions, used, cancelled, failed, estimated cost). GET /v1/usage
TypeScript
// Default: last 30 days
const res = await client.usage();

// Custom: last 7 days
const res7 = await client.usage(7);

console.log(res.data.usage_credit_balance);
console.log(res.data.usage_total_requests);
console.log(res.data.usage_total_generations);
console.log(res.data.usage_total_estimated_cost);

// Per-endpoint breakdown
for (const ep of res.data.usage_endpoints) {
  console.log(ep.endpoint);
  console.log(ep.total_requests);
  console.log(ep.success_count);
  console.log(ep.error_codes);
}

// Per-provider breakdown
for (const prov of res.data.usage_providers) {
  console.log(prov.provider);
  console.log(prov.total_submissions);
  console.log(prov.total_estimated_cost);
}

​
User

​
User account

Get account details for the account bound to the API key. GET /v1/user/account
TypeScript
const res = await client.account();

console.log(res.data.account_id);
console.log(res.data.account_name);
console.log(res.data.account_email);
console.log(res.data.account_is_personal);
console.log(res.data.account_picture_url);
console.log(res.data.account_created_at);

​
User billing

Get the active subscription and credit balance for the account. Returns the plan name, credit balance, subscription status, billing period start/end dates, currency, and whether the subscription is set to cancel at period end. GET /v1/user/billing
TypeScript
const res = await client.billing();

console.log(res.data.account_id);
console.log(res.data.billing_plan);
console.log(res.data.billing_credit_balance);
console.log(res.data.billing_subscription_status);
console.log(res.data.billing_cancel_at_period_end);
console.log(res.data.billing_currency);
console.log(res.data.billing_period_starts_at);
console.log(res.data.billing_period_ends_at);
console.log(res.data.billing_created_at);
console.log(res.data.billing_updated_at);

​
Library

​
Available providers

Get the provider catalog with integration details and capabilities. GET /v1/library/providers
TypeScript
const providers = await client.library.providers();
console.log(providers.data.providers_total);

for (const provider of providers.data.providers) {
  console.log(provider.provider_id);
  console.log(provider.provider_name);
  console.log(provider.provider_description);
  console.log(provider.provider_website);
  console.log(provider.provider_status);
  console.log(provider.babysea_implementation);
}

​
Available models

Get the model catalog with pricing, supported providers, and input/output schemas. GET /v1/library/models
TypeScript
// Model catalog
const res = await client.library.models();

console.log(res.data.models_total);

for (const model of res.data.models) {
  console.log(model.model_identifier);
  console.log(model.model_pricing);
  console.log(model.model_supported_provider);
  console.log(model.schema.generation_ratio);
  console.log(model.schema.generation_output_format);
}

​
Health

​
Provider health

Check per-provider circuit breaker state and failure rates over the last 5-minute window. GET /v1/health/inference/providers
TypeScript
const providers = await client.health.providers();

for (const provider of providers.data.providers) {
  console.log(provider.provider);     // 'replicate' | 'fal' | 'byteplus' | 'cloudflare'
  console.log(provider.status);       // 'healthy' | 'recovering' | 'degraded' | 'unknown'
  console.log(provider.failure_rate);
  console.log(provider.window);       // { total_attempts, failures, successes, duration_seconds }
}

​
Model health

Check which models are currently available across inference providers. GET /v1/health/inference/models
TypeScript
const models = await client.health.models();

for (const model of models.data.models) {
  console.log(model.model_identifier);
  console.log(model.model_pricing);
  console.log(model.providers); // Record<string, { available, raw_model_id }>
}

​
Storage health

Check storage bucket health and latency. GET /v1/health/storage
TypeScript
const storage = await client.health.storage();

console.log(storage.data.service);    // 'storage'
console.log(storage.data.healthy);    // true | false
console.log(storage.data.latency_ms);
console.log(storage.data.bucket);

​
Cache health

Check cache health and latency. GET /v1/health/cache
TypeScript
const cache = await client.health.cache();

console.log(cache.data.service);    // 'redis'
console.log(cache.data.healthy);    // true | false
console.log(cache.data.latency_ms);

​
Financials

​
Cost estimate

Get a cost estimate for a model without executing a generation. Returns per-generation cost, total cost for the requested count, current credit balance, and whether the account can afford it. GET /v1/estimate/{model_identifier}
TypeScript
// Single generation estimate
const res = await client.estimate('bfl/flux-schnell');

// Multi-generation estimate
const res5 = await client.estimate('bfl/flux-schnell', 5);

console.log(res5.data.model_identifier);
console.log(res5.data.assets_count);
console.log(res5.data.cost_per_generation);
console.log(res5.data.cost_total_consumed);
console.log(res5.data.credit_balance);
console.log(res5.data.credit_balance_can_afford);
console.log(res5.data.credit_balance_max_affordable);

// Image model - estimate with count
const resCount = await client.estimate('bfl/flux-schnell', { count: 5 });

// Video model - estimate with duration
const vid = await client.estimate('google/veo-2', { duration: 8 });

// Resolution-priced video model - estimate with duration + resolution
const hd = await client.estimate('bytedance/seedance-1-pro', {
  duration: 8,
  resolution: '1080p',
});

// Audio-priced video model - estimate with duration + resolution + audio
const audioOn = await client.estimate('bytedance/seedance-1.5-pro', {
  duration: 8,
  resolution: '720p',
  audio: true,  // default; charges audio rate
});

const audioOff = await client.estimate('bytedance/seedance-1.5-pro', {
  duration: 8,
  resolution: '720p',
  audio: false, // generates video only at the no-audio rate
});

​
Content management

​
Cancel generation

Cancel an in-progress generation. Available while the generation status is pending or processing. Sends a cancel signal to the upstream provider (best-effort) and refunds credits. POST /v1/content/generation/cancel/{generation_id}
TypeScript
const res = await client.cancelGeneration('...');

console.log(res.data.generation_id);        // generation UUID
console.log(res.data.generation_status);    // 'canceled'
console.log(res.data.provider_cancel_sent); // true or false
console.log(res.data.credits_refunded);     // true or false

​
Delete generation

Delete a generation and permanently remove its output files from storage. The DB record is preserved for audit trail. DELETE /v1/content/{generation_id}
TypeScript
const res = await client.deleteGeneration('...');

console.log(res.data.generation_id);  // generation UUID
console.log(res.data.files_deleted);  // number of storage files removed

​
Generation info

Get the full record for a single generation. Returns current status (pending, processing, succeeded, failed, or canceled), output file URLs when files are still available, model identifier, provider used, provider order, prediction ID, and any error details if the generation failed. When output files were manually deleted or later removed by retention cleanup, generation_output_file is null and generation_removed is present. GET /v1/content/{generation_id}
TypeScript
const res = await client.getGeneration('...');

console.log(res.data.generation_id);
console.log(res.data.generation_status);
console.log(res.data.generation_output_file);

​
List generations

List generations for the authenticated account with offset-based pagination. Returns up to 100 per page, ordered by creation date descending. GET /v1/content/list
TypeScript
// Default: first 50 generations
const res = await client.listGenerations();

// Custom pagination
const page2 = await client.listGenerations({ limit: 20, offset: 20 });

console.log(res.total);   // total count across all pages
console.log(res.limit);
console.log(res.offset);

for (const gen of res.data.generations) {
  console.log(gen.generation_id);
  console.log(gen.generation_status);
  console.log(gen.generation_output_file);
}

​
Content generation

​
Generate image

Submit an image generation request. BabySea attempts the first provider in the configured order and automatically fails over to the next provider on failure. The call returns immediately with a generation_id. Use client.getGeneration() or the webhook flow described in Webhooks to track completion. POST /v1/generate/image/{model_identifier}
TypeScript
const res = await client.generate('google/nano-banana', {
  generation_prompt: 'A cute baby seal on the beach at sunset',
  generation_ratio: '16:9',
  generation_output_format: 'png',
});

console.log(res.data.model_identifier);
console.log(res.data.generation_id);
console.log(res.data.generation_prediction_id);
console.log(res.data.generation_provider_order); // string[] - ordered provider list
console.log(res.data.generation_initialized);     // true

​
Generate video

Submit a video generation request. Same provider failover behavior as image generation. generation_duration is required - the duration in seconds (model-dependent, for example 5 or 8 for google/veo-2). Pricing is per-second. Some models also accept generation_resolution (for example '720p', '1080p') and generation_generate_audio (boolean for audio-priced models). POST /v1/generate/video/{model_identifier}
TypeScript
const res = await client.generateVideo('google/veo-2', {
  generation_prompt: 'A baby seal swimming in crystal clear ocean water',
  generation_ratio: '16:9',
  generation_duration: 5, // seconds
});

console.log(res.data.model_identifier);
console.log(res.data.generation_id);
console.log(res.data.generation_prediction_id);
console.log(res.data.generation_provider_order);
console.log(res.data.generation_initialized);     // true

// Image-to-Video (provide a reference image)
const res2 = await client.generateVideo('google/veo-2', {
  generation_prompt: 'The seal starts swimming',
  generation_duration: 8,
  generation_input_file: ['https://example.com/seal.jpg'],
});

// Resolution-priced model
const res3 = await client.generateVideo('bytedance/seedance-1-pro', {
  generation_prompt: 'A cinematic scene',
  generation_duration: 8,
  generation_resolution: '1080p',
  generation_input_file: ['https://example.com/photo.jpg'],
});

// Audio-capable model - audio enabled (default)
const res4 = await client.generateVideo('bytedance/seedance-1.5-pro', {
  generation_prompt: 'A baby seal barking on a beach',
  generation_duration: 8,
  generation_resolution: '720p',
  generation_generate_audio: true,
});

// Audio-capable model - audio disabled (lower rate)
const res5 = await client.generateVideo('bytedance/seedance-1.5-pro', {
  generation_prompt: 'A time-lapse of ocean waves',
  generation_duration: 8,
  generation_resolution: '1080p',
  generation_generate_audio: false,
});
Provider order Choose which providers to attempt and in what order. BabySea tries the first provider and automatically fails over to the next on failure. Provider order availability depends on the model:
CategoryValid valuesModels
Single-providerreplicateResolution-critical models (e.g. some video models)
2-providerreplicate, fal or fal, replicateMost image/video models
BytePlusAbove + byteplus, replicate, fal or byteplus, fal, replicateByteDance family models
Cloudflarecloudflare, replicate, falCloudflare-supported image models
Check client.library.models() to see which provider orders each model accepts. Current SDK video methods do not accept Cloudflare-first provider order values because the public video route only exposes Replicate, FAL, and BytePlus combinations.
TypeScript
// Single-provider (resolution-critical models)
const res = await client.generateVideo('minimax/video-01-director', {
  generation_prompt: 'Ocean waves',
  generation_duration: 5,
  generation_provider_order: 'replicate',
});

// 2-provider (most models)
const res2 = await client.generate('google/nano-banana', {
  generation_prompt: 'Ocean waves',
  generation_provider_order: 'fal, replicate',
});

// 3-provider with BytePlus (bytedance family models)
const res3 = await client.generate('bytedance/seedream-4', {
  generation_prompt: 'Ocean waves',
  generation_provider_order: 'byteplus, replicate, fal',
});

// 3-provider with Cloudflare (cloudflare-supported models)
const res4 = await client.generate('bfl/flux-schnell', {
  generation_prompt: 'Ocean waves',
  generation_provider_order: 'cloudflare, replicate, fal',
});
Model-specific parameters Some models accept parameters beyond the standard schema. Call client.library.models() first - each model’s specific_schema is an array of accepted extra parameter keys. Pass them alongside the standard fields:
TypeScript
// 1. Check what extra params a model accepts
const catalog = await client.library.models();
const model = catalog.data.models.find(m => m.model_identifier === 'qwen/image');
console.log(model?.specific_schema);
// e.g. ['generation_negative_prompt', 'generation_seed', 'generation_guidance', ...]

// 2. Pass them directly in the generate call (all use the generation_ prefix)
const res = await client.generate('qwen/image', {
  generation_prompt: 'A landscape',
  generation_negative_prompt: 'blurry, low quality', // qwen/image specific
  generation_seed: 42,                               // qwen/image specific
  generation_guidance: 7,                            // qwen/image specific (replicate provider)
});