Skip to main content

Callirra Developer API

Use https://api.callirra.com for developer requests. GET /v1/capabilities lists the interfaces available on the server you connect to. Use the model catalogs to discover available IDs and supported settings before submitting generation.

One account and one API key

Create a key in API Keys, then send it as Authorization: Bearer sk-cal-…. Keys are checked on every request: revocation, expiry and account suspension apply immediately, with the configured per-key request limit. Website session JWTs are not accepted at these developer endpoints. Keep credentials in environment variables; never embed them in a browser bundle.

Image/video generation, multimodal conversation, prompt polish, audio, private assets, Constellation and AI Filmmaker (Stories) use the same account. Ordinary AI chat, Constellation creation/execution and Stories authoring/new production require an active Starter or higher subscription, including API calls. Paid generation steps consume the same credit balance as the website. Editing tools marked free do not add generation credits. Existing owned Stories, history, downloads, cancellation, accepted-request recovery and local exports remain accessible after expiry, subject to ownership and media-retention checks. A denied new Stories operation returns HTTP 403 with stories.subscription_required.

export CALLIRRA_API_KEY='sk-cal-REPLACE_WITH_YOUR_KEY'
curl https://api.callirra.com/v1/capabilities \
  -H "Authorization: Bearer $CALLIRRA_API_KEY"

Pick the right protocol

TaskDiscoveryProtocol
Credits and usageGET /v1/balance, GET /v1/usageCurrent balances and bounded recent usage
Existing compatible text completionsGET /v1/models/v1/chat/completions, compatible JSON or token SSE for models advertising that interface
Current multimodal conversationGET /v1/chat/catalogDurable sessions, 202 {run}, owner-scoped run reads and SSE run snapshots
Smart / directed prompt polishChat catalog and /polish/priceFixed retail quote, stable operation ID, preview result
ImagesGET /v1/modelsPOST /v1/images/generations
VideosGET /v1/models/v1/videos jobs and polling
Speech, music, soundsGET /v1/audio/modelsQuote, accept quoted job, poll, download signed output
Assets and collections/v1/assets, /v1/asset-collectionsOwner-scoped list / read / organize / rename / delete
Constellation and media toolsGET /v1/constellation/catalogProject graph, quote, budget-confirmed run, history and AI plan
Stories authoring (HTTP)GET /v1/stories/catalog with API keyVersioned projects/episodes, review, separately billed plans, quote/budget production, language exports and request recovery

The current chat catalog is a durable conversation protocol. Do not assume its IDs work with a generic OpenAI Chat Completions SDK. /v1/models identifies the corresponding interface; unsupported use receives assistant_extension_required with the correct endpoint. Chat SSE sends complete safe run snapshots, not OpenAI choices[].delta chunks.

The canonical dialogue paths are /v1/chat/* for API keys and /api/v1/chat/* for website sessions. Existing /v1/assistant/* and /api/v1/assistant/* paths remain deprecated aliases with identical bodies, ownership checks, run IDs, idempotency, SSE and billing. Alias responses include Deprecation: true and a Link to the matching canonical path; aliases are hidden from generated route documentation. /v1/chat/completions remains the existing OpenAI-compatible protocol. Existing assistant.* error codes and billing feature identifiers remain stable for published clients.

Multimodal conversations

  1. Read /v1/chat/catalog; choose a public model ID and inspect image, video, sound and context capabilities.
  2. Create a session with POST /v1/chat/sessions, optionally {"title":"Product story"}.
  3. Upload references through POST /v1/media/references/upload using multipart field file. Use the returned `assetId` for attachments; id is a different storage identifier.
  4. Submit a turn to POST /v1/chat/sessions/{sessionId}/messages with a stable requestId.
  5. Read /v1/chat/runs/{runId} or its /events SSE stream until a terminal result. A network disconnect does not cancel accepted work.
{
  "action": "chat",
  "requestId": "product-lighting-turn-001",
  "modelId": "gpt-6-1-sol",
  "instruction": "Compare these lighting directions and suggest a concise image prompt.",
  "attachments": [{"id":"OWNED_ASSET_ID","mediaType":"image","role":"reference"}],
  "locale": "en"
}

Text, image and video attachments use the selected model's capabilities. Native sound understanding is available only where the catalog says so. Historical messages and accessible historical media remain associated with the session; do not resend an old user turn as a new paid request. Capacity endpoints preview the server's context preparation without inference or billing. The original history remains stored when older context is locally condensed.

Chat endpoint groups

All paths below start with /v1/chat:

Methods / pathOperation
GET /catalogSafe customer model catalog and public capabilities
GET, POST /sessionsBounded history or new session
GET, PATCH, DELETE /sessions/{id}Read, rename or remove owned conversation
GET, POST /sessions/{id}/messagesOlder message page or new turn
POST /context-window, /sessions/{id}/contextRead-only capacity preparation
POST /contextExplicitly resolve owned current generator material for a visible draft
GET /polish/allowanceDedicated daily polish allowance
POST /polish/price, /polishFixed polish price and confirmed submission
GET /runs/{id}, /runs/{id}/eventsSafe result or SSE snapshots
POST /runs/{id}/cancelSupported cancellation / reconciliation action
GET /pending-billingRecover own unfinished work and unresolved billing

Polish uses the same request contract as the website. Supply expectedCredits and expectedPaidCredits from the current price response when confirming. A changed price returns a conflict before a new model call or debit. Dedicated daily allowance is used first, then ordinary credits; failed tasks refund their original source. Daily Starter / Pro / Max / Max-L allowances are 10 / 30 / 40 / 50 public credits, reset at UTC midnight and do not accumulate.

Image and video request parity

Image recovery

Use POST /v1/images/generations for an image. Generate a fresh caller key for each intended image request and keep it with the submitted body.

curl https://api.callirra.com/v1/images/generations \
  -H "Authorization: Bearer $CALLIRRA_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: coastal-banner-001' \
  -d '{"model":"gpt-image-2","prompt":"A coastal mountain highway at sunrise","size":"2k"}'

Images remain synchronous. To make a request recoverable, send a stable caller Idempotency-Key header (1–128 visible ASCII characters without spaces) with POST /v1/images/generations and preserve the exact settings. An identical replay returns 409 image_request_exists without generating again. The error carries an owner-scoped durable request_id and, when an image job row exists, job_id and status_url. Read the returned relative status_url with the same API key; otherwise list by the durable request_id. Older ledger-only requests may have no job row; keep the original caller key and inspect owned assets/usage before separately authorizing another generation. A changed request with the same key returns a conflict.

Method / pathRead-only recovery
GET /v1/images/jobs{jobs,total}; filters: take (1–100, default 20), skip (nonnegative offset), status (queued, running, completed, failed, cancelled), model, request_id
GET /v1/images/jobs/{id}{job}; id is the database job ID returned by a job list or replay error, not the durable requestId

The list's request_id filter uses the durable ID returned by the API, not the original caller key. Both GET routes enforce API-key authentication, ownership and media-retention rules; they never submit generation. Completed output URLs come from the owned asset library, and charges come from usage history. SDK listImageJobs/getImageJob, CLI images list/get, MCP list_image_jobs/get_image_job and Python images list/get expose the same reads.

Media settings

POST /v1/images/generations uses the website's request schema, including image_input as a URL or URL array, reference_images, studio metadata and prompt-free layer decomposition. POST /v1/videos preserves reference image/video/audio arrays and explicit false controls. Global parsing ceilings are 30 input_images, 10 input_videos and 10 audio_input entries; individual models apply smaller limits. Canonical duration_seconds takes precedence over legacy duration when both are supplied.

Seedance 2.x

ModelStandard IDUltra-Wide ID
Seedance 2.0seedance-2seedance-2-wide
Seedance 2.0 Fastseedance-2-fastseedance-2-fast-wide
Seedance 2.0 Miniseedance-2-miniseedance-2-mini-wide
Seedance 2.5seedance-2.5seedance-2.5-wide

All eight require an active Starter or higher subscription. Use these IDs in new requests and use GET /v1/models to check per-model modes, resolution, durations, reference limits and supported controls. Existing legacy IDs remain accepted on input. Standard models accept authorized real-face references in many everyday workflows. Ultra-Wide provides broader moderation, and acceptance varies with the selected model, reference media and prompt. See Seedance moderation.

Each scene in capabilities.scene reports its highest supported prompt length as promptMax. If the scene also reports shortPromptMax, the extended range starts at longPromptMin and requires compatible settings. The optional longPromptResolutionOptions, longPromptReferenceModes and longPromptReferenceImagesMax fields describe those settings. The generator shows the effective character limit for the selected settings and references. Over-limit requests receive HTTP 400 with prompt as the invalid field.

With no reference video, generation is priced by output duration. When a reference video is supplied, rates and billable duration vary by configuration. Check credit costs and review the exact configuration before submission.

curl https://api.callirra.com/v1/videos \
  -H "Authorization: Bearer $CALLIRRA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"seedance-2","prompt":"A slow dolly toward a mountain cabin at dawn","mode":"text_to_video","resolution":"720p","duration_seconds":5,"aspect_ratio":"16:9"}'
Methods / pathOperation
GET, POST /v1/videosList owned video jobs or create a queued job
GET /v1/videos/{id}Poll the accepted job and read its result
POST /v1/videos/{id}/cancelCancel an eligible owned job
GET /v1/videos/{id}/contentDownload completed video using API-key authentication

MiniMax H3

MiniMax H3 uses model:"minimax-h3" and these additional public fields:

FieldValues
minimax_h3_variantstandard or multimode; omission uses standard except 1440P implies multimode
minimax_h3_style_presetMultimode only: live_action_drama, live_action_drama_realistic, live_action_action, live_action_action_realistic, anime_drama, anime_action
minimax_h3_modeReference conditioning; first/last-frame modes only where the selected standard tier supports them
resolution480P, 768P, 960P, 1080P, 1440P, 2K; 1088P is accepted as an alias of public 1080P

Standard 480P/768P supports 1–15 seconds; standard 1080P supports 1–10 seconds. Standard 960P is image-to-video cinematic quality only (1–15 seconds, no seed). Multimode supports 480P/768P/1080P/1440P, 1–15 seconds, 16:9 or 9:16, reference conditioning and up to nine images plus three audio clips. Image-to-video requires at least one image; text-to-video cannot receive images. Multimode does not accept first/last-frame conditioning, video input, 960P or 2K. Explicit standard at 1440P is rejected. Existing 768P video-to-video and 2K capabilities remain in the live model catalog.

{"model":"minimax-h3","prompt":"A cinematic conversation at sunset","mode":"text_to_video","resolution":"1440P","duration_seconds":15,"aspect_ratio":"16:9","minimax_h3_variant":"multimode","minimax_h3_style_preset":"live_action_drama_realistic"}

SDK createVideo, CLI gen video --body-file, MCP create_video and Python generate-video --input transport these fields. CLI/Python also expose --minimax-variant and --minimax-style-preset. H3 fields are stored with the accepted job and restored by the worker and history views.

Audio jobs

Use the public catalog to choose mode, voice, format and any supported duration or lyrics controls. Unsupported fields fail validation. Reference-voice models advertise their owned-audio and emotion controls explicitly; see IndexTTS2 below.

curl https://api.callirra.com/v1/audio/models \
  -H "Authorization: Bearer $CALLIRRA_API_KEY"
curl https://api.callirra.com/v1/audio/quote \
  -H "Authorization: Bearer $CALLIRRA_API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"MODEL_ID_FROM_CATALOG","mode":"tts","text":"Welcome to your creative space.","voice":"VOICE_ID_FROM_CATALOG","format":"mp3"}'

The body above uses placeholders. Substitute a model and voice from the selected server's catalog with the settings it supports.

Methods / pathOperation
GET /v1/audio/modelsPublic model capabilities and retail quote inputs
POST /v1/audio/quoteExact expiring quote for the immutable request
POST /v1/audio/generationsAudioRequest + request_id + quote_id + expected_credits? → 202 {job}
GET /v1/audio/generationsOwned history; take 1–60 (default 20), offset cursor and request_id recovery
GET /v1/audio/generations/{id}Status, public credits and signed outputs
POST /v1/audio/generations/{id}/cancelCancel an owned job while it is queued
POST /v1/audio/generations/{id}/settleExplicit maximum_credits approval for a known additional settlement

Reuse the same request_id and exact body after a lost submission response. Request lookup can recover an uncertain acceptance without paying for a second generation. A quote alone does not start generation. Settlement approves the existing task; it does not regenerate content. Download completed output while its signed URL is valid; re-read the owned job to obtain a fresh URL later.

IndexTTS2 reference voice

When audio models advertises available indextts2, use mode:"tts", text (1–2048 characters) and reference_audio as an owned MP3/WAV library asset ID, obtained from upload assetId. emotion_mode:"reference" uses the voice reference; "audio" requires owned emotion_reference_audio; "vector" requires exactly eight emotion_vector values in 0–1.4. Only provide the emotion input for the selected mode. emotion_random is optional. This model has no preset voice, speed, target-duration or emotion-text control.

{"model":"indextts2","mode":"tts","text":"Welcome to your creative space.","reference_audio":"OWNED_VOICE_ASSET_ID","emotion_mode":"reference","emotion_random":false,"reservation_credits":1}

reservation_credits is an initial hold (0.01–120 credits, default 1), not a duration prediction or final-price cap. Quotes identify billing_basis:"actual_output_duration" and credits_per_second:0.1; final credits follow measured output duration, with unused hold refunded. Additional credits require the existing explicit settlement action. Discover model availability and quote exact settings before creating the job.

Design a voice from text

When the catalog reports seed-audio-voice-design as available, send a description of an original voice and the script it should speak. The trimmed description accepts 10–500 UTF-16 code units and the script accepts 1–2200. Use this body for both the quote and the generation job.

{"model":"seed-audio-voice-design","mode":"tts","voice_description":"A warm, low voice with clear diction and a gentle storytelling pace.","text":"The bookstore opens at dawn."}

The quote reserves 45 credits. Verified output usage settles at 0.375 credits per generated second and returns the unused hold. The job returns a playable MP3 in the owned library. The response contains audio, so a subsequent design request creates a new voice.

Assets and collections

Uploads from a workspace or API join the same private account library. Generated images, videos and audio are registered there automatically. A collection groups references and outputs without copying media bytes.

Methods / pathOperation
POST /v1/media/references/uploadMultipart file, optional space, optional owned collection_id
GET /v1/assetsFilter by mediaType, q, favorite, source, collection_id, sort; take and cursor paging
GET /v1/assets/{id}Owner and retention validated read with fresh signed links
POST /v1/assetsRegister supported owned media; server revalidates storage/job ownership
PATCH /v1/assets/{id}title, favorite, collection_id
POST /v1/assets/organizeAtomic owned batch ids plus favorite / collection change
DELETE /v1/assets/{id}, POST /v1/assets/deleteSoft-delete one item or bounded owned batch
GET, POST /v1/asset-collectionsList or create a named collection
PATCH, DELETE /v1/asset-collections/{id}Rename or remove collection; removing it keeps the assets

Multipart supports images up to 20 MiB, supported audio up to 15 MiB and supported video up to 100 MiB. Actual supported containers and model limits still apply; a successful upload is not a promise every model accepts that media. assetId identifies the library item; id identifies the stored reference. collection_id=none lists ungrouped assets. Signed URLs are temporary access capabilities: share them only deliberately, and do not log them in public examples.

Constellation and deterministic media tools

Read GET /v1/constellation/catalog for the actual graph nodes, ports, models, config fields and templates. Projects use the same ConstellationGraph schema as the website. Text, owned assets, image/video/audio generation, prompt polish, final output and deterministic media processing can be connected through typed ports.

Methods / pathOperation
GET, POST /v1/constellation/projectsList or create own graph; creation supports stable requestId
GET, PATCH, DELETE /v1/constellation/projects/{id}Read, revision-checked update or remove
POST /v1/constellation/quote{"graph": …} → validation, graph hash and public credit budget
GET, POST /v1/constellation/projects/{id}/runsOwned history or explicit requestId, graphHash, maximumCredits acceptance
GET /v1/constellation/runs/{id}Progress, per-step results and total public credits
POST /v1/constellation/runs/{id}/cancelCancel own run under existing service rules
POST /v1/constellation/projects/{id}/planExplicit instruction, public modelId, stable requestId and optional locale
GET /v1/constellation/plans/{id}Read AI planning result before applying a graph
POST /v1/constellation/toolsRun one supported deterministic media tool on owned asset IDs

Quote the exact graph, keep its hash, and require the user's budget confirmation before starting paid work. A stale revision or changed graph fails instead of silently running a different project. AI planning proposes a graph; applying and running it remain explicit separate actions. Trimming, resizing, extracting a frame or audio track, joining video and mixing audio reuse the same owned-media validation as the website.

The audio-pad node uses the same tools/run contract. It places complete owned speech at a millisecond offset and pads with silence to the target duration. It creates a derived WAV without new generation credits and fails if the full recording does not fit. Check its availability and fields in the workflow catalog.

Stories HTTP recovery

Stories requests use public display credits, current project/episode revisions and stable requestId values. When a plan, production or export response is uncertain, look up the accepted record by request ID, with kind=plan, production or export. Preserve the original body and ID before retrying. Continuing a failed or cancelled production uses a separate quote with resumeFromProductionId, which validates reusable media against the current version. Submit Stories directly over HTTP with your API key.

Methods / path under /v1/storiesOperation
GET /catalogAvailable models, workflow controls and schema
GET, POST /projectsList or create projects
GET, PATCH, DELETE /projects/{id}Owned project read, revision-checked update or deletion
POST /projects/{id}/episodesCreate an episode
GET /projects/{id}/revisionsProject revision summaries
POST /projects/{id}/restoreCreate a new revision from project history
GET, PATCH, DELETE /episodes/{id}Owned episode read, revision-checked update or deletion
POST /episodes/{id}/actionsReview approval, lock or candidate actions
POST /episodes/{id}/draftApply a reviewed project or episode draft
POST /episodes/{id}/restoreCreate a new revision from episode history
GET /episodes/{id}/revisionsEpisode snapshots
GET /revisions/{id}Read an owned revision snapshot
GET /assetsList owned Stories assets with temporary URLs
GET /episodes/{id}/plansPlan history
POST /episodes/{id}/planSubmit a separately billed plan
GET /plans/{id}Plan status, actual credits, draft and diagnostics
GET /episodes/{id}/requests/{requestId}Locate an accepted plan, production or export
POST /episodes/{id}/quoteQuote the selected version, shots and languages
GET, POST /episodes/{id}/productionsProduction history or accept quoted work within a budget
GET /productions/{id}Progress, costs, candidate media and export ID when available
POST /productions/{id}/cancelCancel an owned production
GET, POST /episodes/{id}/exportsExport history or export a fixed snapshot
GET /exports/{id}Status and completed signed video URL
GET /exports/{id}/files/{format}Download an available srt, vtt or json file

Credits and errors

Chat settlement uses US$0.01 per public credit as its reference. Subscription tiers have their own effective per-credit purchase costs.

Legacy image/video/balance/usage payloads retain their documented internal integer accounting unit: 100 internal units = 1 public credit. Audio and workflow quote DTOs expose public credits. Do not divide every numeric field by 100; preserve raw responses and follow each contract. SDK, CLI and MCP keep consistent typed fields for these distinct protocols.

Never retry a paid POST with a fresh operation ID merely because the network timed out. Read the original task, session or request ID first. Polling has a bounded deadline; timeout means the task may still be running. Completion, failure, cancellation and awaiting-payment states have different meanings.

Errors retain the public error envelope and request ID. Show actionable validation and permission errors to users. Do not surface internal supplier names, procurement costs, secret keys or upstream model identifiers. For support, send the Callirra request ID and public task ID rather than credentials.

Official integrations

Use the server's capability response and your installed tool's help or discovery output to confirm support for a particular route.

  • TypeScript SDK: npm install @callirra/client. npm package and readme
  • CLI: npm install -g @callirra/cli, then callirra --help. CLI setup
  • MCP: npm install -g @callirra/mcp, then configure your MCP client to start callirra-mcp with CALLIRRA_API_KEY. MCP setup
  • Agent Skill: Download the ZIP and follow the installation steps for your agent. Skill setup