Skip to content
Glacier AIDOCUMENTATION
DOCS / USER GUIDE

API integration

Use an API key to upload media, request quotes, submit asynchronous tasks and fetch results.

Credentials and base URL

Section titled “Credentials and base URL”

Create a key in Account → API. Save the full secret when it is created; the key list only displays its identifying prefix. Use a read-only key for queries and a key with write permission for uploads and processing.

The public API base is https://app.berserkapi.com/api/v1. Send Authorization: Bearer YOUR_API_KEY. API keys work on /api/v1 endpoints, not on account or administrator endpoints. Keep keys on your server rather than in public browser code.

Terminal window
curl 'https://app.berserkapi.com/api/v1/tools'   -H "Authorization: Bearer $GLACIER_API_KEY"

This returns the current tool catalog, parameters, limits and prices. Use those values instead of hard-coding prices or engine-dependent options.

Processing sequence

Section titled “Processing sequence”
  1. Read upload limits with GET /api/v1/assets/upload-limits.
  2. Request upload credentials with POST /api/v1/assets/uploads. Upload the bytes to the returned storage URL using the returned method and fields; send your API key only to the application API.
  3. Confirm upload completion with POST /api/v1/assets/{assetId}/complete and wait for the asset to be ready.
  4. Get a quote with POST /api/v1/tasks/quote, using the intended assetId, toolId and params. A non-null problem means the task cannot currently be submitted.
  5. Submit the same selection to POST /api/v1/tasks, including the quote ID while valid and a unique Idempotency-Key header.
  6. Follow the returned Location or urls.status, respecting Retry-After, until the task reaches a terminal state.
  7. On success, request GET /api/v1/tasks/{taskId}/result for output URLs or the report.

Retries and cost control

Section titled “Retries and cost control”

Reuse the same idempotency key and request body when retrying the same logical submission. Using a new key may create another paid task. Reusing a key with different parameters returns 409.

Use a valid quoteId to submit against a quote, or set maxCostCredits to reject a task whose cost exceeds your limit. File links are temporary; call the result endpoint again to refresh them without processing again.

Errors

Section titled “Errors”
Status Action
401 / 403 Check the key, expiry, revocation and permissions
402 Check the account’s credit balance
409 Read detail: parameters, quote or task state may conflict
410 The requested result or task is no longer available
422 Correct the request fields against the schema
429 Respect Retry-After and reduce request concurrency
503 Processing capacity or a required service is temporarily unavailable

See the live API reference for the exact request and response schemas of the deployed version. The reference is separate from these static usage guides.