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
| Task | Discovery | Protocol |
|---|---|---|
| Credits and usage | GET /v1/balance, GET /v1/usage | Current balances and bounded recent usage |
| Existing compatible text completions | GET /v1/models | /v1/chat/completions, compatible JSON or token SSE for models advertising that interface |
| Current multimodal conversation | GET /v1/chat/catalog | Durable sessions, 202 {run}, owner-scoped run reads and SSE run snapshots |
| Smart / directed prompt polish | Chat catalog and /polish/price | Fixed retail quote, stable operation ID, preview result |
| Images | GET /v1/models | POST /v1/images/generations |
| Videos | GET /v1/models | /v1/videos jobs and polling |
| Speech, music, sounds | GET /v1/audio/models | Quote, accept quoted job, poll, download signed output |
| Assets and collections | /v1/assets, /v1/asset-collections | Owner-scoped list / read / organize / rename / delete |
| Constellation and media tools | GET /v1/constellation/catalog | Project graph, quote, budget-confirmed run, history and AI plan |
| Stories authoring (HTTP) | GET /v1/stories/catalog with API key | Versioned 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
- Read
/v1/chat/catalog; choose a public model ID and inspect image, video, sound and context capabilities. - Create a session with
POST /v1/chat/sessions, optionally{"title":"Product story"}. - Upload references through
POST /v1/media/references/uploadusing multipart fieldfile. Use the returned `assetId` for attachments;idis a different storage identifier. - Submit a turn to
POST /v1/chat/sessions/{sessionId}/messageswith a stablerequestId. - Read
/v1/chat/runs/{runId}or its/eventsSSE 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 / path | Operation |
|---|---|
GET /catalog | Safe customer model catalog and public capabilities |
GET, POST /sessions | Bounded history or new session |
GET, PATCH, DELETE /sessions/{id} | Read, rename or remove owned conversation |
GET, POST /sessions/{id}/messages | Older message page or new turn |
POST /context-window, /sessions/{id}/context | Read-only capacity preparation |
POST /context | Explicitly resolve owned current generator material for a visible draft |
GET /polish/allowance | Dedicated daily polish allowance |
POST /polish/price, /polish | Fixed polish price and confirmed submission |
GET /runs/{id}, /runs/{id}/events | Safe result or SSE snapshots |
POST /runs/{id}/cancel | Supported cancellation / reconciliation action |
GET /pending-billing | Recover 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 / path | Read-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
| Model | Standard ID | Ultra-Wide ID |
|---|---|---|
| Seedance 2.0 | seedance-2 | seedance-2-wide |
| Seedance 2.0 Fast | seedance-2-fast | seedance-2-fast-wide |
| Seedance 2.0 Mini | seedance-2-mini | seedance-2-mini-wide |
| Seedance 2.5 | seedance-2.5 | seedance-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 / path | Operation |
|---|---|
GET, POST /v1/videos | List owned video jobs or create a queued job |
GET /v1/videos/{id} | Poll the accepted job and read its result |
POST /v1/videos/{id}/cancel | Cancel an eligible owned job |
GET /v1/videos/{id}/content | Download completed video using API-key authentication |
MiniMax H3
MiniMax H3 uses model:"minimax-h3" and these additional public fields:
| Field | Values |
|---|---|
minimax_h3_variant | standard or multimode; omission uses standard except 1440P implies multimode |
minimax_h3_style_preset | Multimode only: live_action_drama, live_action_drama_realistic, live_action_action, live_action_action_realistic, anime_drama, anime_action |
minimax_h3_mode | Reference conditioning; first/last-frame modes only where the selected standard tier supports them |
resolution | 480P, 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 / path | Operation |
|---|---|
GET /v1/audio/models | Public model capabilities and retail quote inputs |
POST /v1/audio/quote | Exact expiring quote for the immutable request |
POST /v1/audio/generations | AudioRequest + request_id + quote_id + expected_credits? → 202 {job} |
GET /v1/audio/generations | Owned 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}/cancel | Cancel an owned job while it is queued |
POST /v1/audio/generations/{id}/settle | Explicit 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 / path | Operation |
|---|---|
POST /v1/media/references/upload | Multipart file, optional space, optional owned collection_id |
GET /v1/assets | Filter 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/assets | Register supported owned media; server revalidates storage/job ownership |
PATCH /v1/assets/{id} | title, favorite, collection_id |
POST /v1/assets/organize | Atomic owned batch ids plus favorite / collection change |
DELETE /v1/assets/{id}, POST /v1/assets/delete | Soft-delete one item or bounded owned batch |
GET, POST /v1/asset-collections | List 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 / path | Operation |
|---|---|
GET, POST /v1/constellation/projects | List 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}/runs | Owned 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}/cancel | Cancel own run under existing service rules |
POST /v1/constellation/projects/{id}/plan | Explicit instruction, public modelId, stable requestId and optional locale |
GET /v1/constellation/plans/{id} | Read AI planning result before applying a graph |
POST /v1/constellation/tools | Run 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/stories | Operation |
|---|---|
GET /catalog | Available models, workflow controls and schema |
GET, POST /projects | List or create projects |
GET, PATCH, DELETE /projects/{id} | Owned project read, revision-checked update or deletion |
POST /projects/{id}/episodes | Create an episode |
GET /projects/{id}/revisions | Project revision summaries |
POST /projects/{id}/restore | Create a new revision from project history |
GET, PATCH, DELETE /episodes/{id} | Owned episode read, revision-checked update or deletion |
POST /episodes/{id}/actions | Review approval, lock or candidate actions |
POST /episodes/{id}/draft | Apply a reviewed project or episode draft |
POST /episodes/{id}/restore | Create a new revision from episode history |
GET /episodes/{id}/revisions | Episode snapshots |
GET /revisions/{id} | Read an owned revision snapshot |
GET /assets | List owned Stories assets with temporary URLs |
GET /episodes/{id}/plans | Plan history |
POST /episodes/{id}/plan | Submit 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}/quote | Quote the selected version, shots and languages |
GET, POST /episodes/{id}/productions | Production history or accept quoted work within a budget |
GET /productions/{id} | Progress, costs, candidate media and export ID when available |
POST /productions/{id}/cancel | Cancel an owned production |
GET, POST /episodes/{id}/exports | Export 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, thencallirra --help. CLI setup - MCP:
npm install -g @callirra/mcp, then configure your MCP client to startcallirra-mcpwithCALLIRRA_API_KEY. MCP setup - Agent Skill: Download the ZIP and follow the installation steps for your agent. Skill setup