DOCSEARCHbyAlgolia
Submit Docs

BabySea Documentation

website·Indexed 32 days ago

https://docs.babysea.ai

An execution control plane for generative AI that provides a regional /v1 API and TypeScript SDK for running image and video generation through a single response schema. Features include asynchronous workload management, webhook notifications, a browser-based playground for testing model schemas, and a comprehensive dashboard for managing API keys, billing, and usage metrics.

Tokens
15.1K
Snippets
56
Records
115
Agent score
52%

What's inside BabySea

  1. Overview of BabySea Generative Media API

    BabySea acts as an execution control plane for generative media, allowing developers to run image and video generation through a single regional API and a consistent response schema. It provides a unified schema for common fields (e.g., generation_prompt, generation_ratio), provider routing via generation_provider_order to handle failovers, and a standardized credit system where 1 credit equals $1 USD.

  2. Test BabySea API requests using the Playground

    The BabySea Playground is a public browser console used to test image and video generation requests. It utilizes the same /v1 API routes as production code, allowing developers to verify model schemas, regional endpoints, and content actions before implementation. Access the playground at https://us.babysea.ai/playground.

  3. Monitor account usage and performance via the Metrics dashboard

    The Metrics dashboard provides account-level visibility into request volume, generation outcomes, credit spend, webhook delivery, and latency trends for a selected team account. It is a read-only page accessible to all team roles.

    Key data sections include:

    • Plan card: Displays current plan, subscription state, renewal date, credit balance, and credits used in the current period.
    • Content generation: Tracks counts for succeeded, failed, and canceled requests, including failover counts and summaries of models, providers, and outputs.
    • API usage: Breaks down requests by status, method, endpoint, API key, and webhook delivery outcomes.
    • Performance: Provides latency metrics including P50, P95, P99, average latency, inference time, and breakdowns of generation errors.

  4. Understand the BabySea account audit feed (Activity)

    The Activity feed is a searchable audit log that records important events across the dashboard, API, billing, webhooks, credits, and compliance. It is visible to all team roles and is read-only. Use the Activity feed to determine 'who changed what' in the account, as opposed to the Logs page which tracks per-request API traffic.

  5. Understand BabySea credit balance and currency

    BabySea uses a credit-based spending balance where 1 credit equals $1 USD. Balances are tracked with precision up to three decimal places.

  6. Purchase and manage credit packs

    Credit packs are one-time add-ons that increase the account credit balance. To purchase a credit pack, the following requirements must be met:

    1. The account must have an active subscription.
    2. The user must be the primary-owner.
    3. The checkout must complete successfully via the billing provider.

    Note: If a subscription becomes inactive before the payment webhook is processed, credits will not be allocated automatically and will require manual review.

    PackCredits added
    $1010.000
    $2525.000
    $5050.000
    $100100.000
    $500500.000
    $1,0001,000.000

  7. Verify BabySea webhook signatures

    BabySea signs the raw JSON body using HMAC-SHA256. The signed payload consists of the unix timestamp and the raw body: <unix_timestamp>.<raw_json_body>.

    It is recommended to use the verifyWebhook() function from the TypeScript SDK, which validates the signature and ensures the timestamp is within the default tolerance window of 300 seconds.

    import {
  isCreditLowBalance,
  isGenerationCompleted,
  verifyWebhook,
} from 'babysea/webhooks';

export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get('X-BabySea-Signature') ?? '';

  const event = await verifyWebhook(
    rawBody,
    signature,
    process.env.BABYSEA_WEBHOOK_SECRET!,
  );

  if (isGenerationCompleted(event)) {
    await saveOutput(
      event.webhook_data.generation_id,
      event.webhook_data.generation_output_file ?? [],
    );
  }

  if (isCreditLowBalance(event)) {
    await notifyBillingOwner(event.webhook_data.current_balance);
  }

  return new Response('ok');
}

  8. Delete a team account

    Team deletion is a destructive action and is only available if enabled for the account. Only the primary-owner can perform this action. Before deleting, it is recommended to review billing, API keys, webhooks, custom domains, logs, and stored generations.

  9. Use generateAndWait for synchronous-like generations

    The generateAndWait() method creates a generation and polls automatically until it succeeds or fails. It is ideal for scripts and demos. It throws BabySeaGenerationFailedError if the process fails or is canceled.
    const generation = await client.generateAndWait(
  'bfl/flux-schnell',
  {
    generation_prompt: 'A baby seal playing on Arctic ice',
    generation_ratio: '1:1',
  },
  {
    timeout: 120_000, // Total timeout for polling
    interval: 2_000,  // Polling interval
  },
);

console.log(generation.data.generation_output_file);

  10. Production checklist for BabySea AI

    When moving to production, follow these best practices:

    • Use Generate Only keys for workers to limit scope.
    • Implement an IP allowlist for fixed infrastructure.
    • Use Idempotency-Key for all queue or user-triggered retries.
    • Replace polling with webhook endpoints for high-traffic paths.
    • Use specific error codes to distinguish between retryable provider errors and request issues.
    • Monitor logs, credits, and activity via the dashboard.

  11. Verify BabySea webhook signatures

    Use verifyWebhook to validate the X-BabySea-Signature header (which contains a timestamp and HMAC) against your BABYSEA_WEBHOOK_SECRET. Use isGenerationCompleted to check if the event indicates a finished generation.
    import { isGenerationCompleted, verifyWebhook } from 'babysea/webhooks';

export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get('X-BabySea-Signature') ?? '';

  const event = await verifyWebhook(
    rawBody,
    signature,
    process.env.BABYSEA_WEBHOOK_SECRET!,
  );

  if (isGenerationCompleted(event)) {
    console.log(event.webhook_data.generation_output_file);
  }

  return new Response('ok');
}

  12. Implement retry logic for BabySea API errors

    When handling errors, prioritize the retryable field in the error envelope over the HTTP status code, as some 5xx provider failures are not retryable.

    Retry Guidelines:

    • Retry (Yes): When retryable: true (use exponential backoff), HTTP 429 (respect Retry-After), or HTTP 5xx where retryable: true.
    • Do Not Retry (No): HTTP 4xx (except 429), or when the error type is provider_credits_exhausted (choose another model/provider instead).