API reference
Programmatic access to Cosmiq’s generation. The supported surface is the MCP server
(https://www.cosmiq.studio/api/mcp) and its operations, authenticated with an API key.
Access — API & MCP are currently invite-only (private beta). When enabled, mint an API key in Settings → API keys.
Authentication
Send your API key as a Bearer token:
Authorization: Bearer csk_••••••••- Claude (web connector): authenticates via the Cosmiq consent screen (no key to paste). See MCP.
- Claude Desktop / Code / scripts: use the API key (Bearer).
Conventions
- Board — the canvas your result lives on. Most operations return a board URL:
https://www.cosmiq.studio/boards/<id>. - Space — an optional workspace that groups related boards. Pass a name; it’s created if missing and reused next time. It’s just organization, not a brand.
- Credits — generating images/videos spends credits (like the app). Building a board without generating is free.
Aspect ratios (format)
| Value | Use |
|---|---|
9:16 | Reels / Stories — default for create / campaign / edit |
4:5 | Feed post — default for carousel |
1:1 | Square / ad covers |
16:9 | Wide / web |
3:4, 2:3 | Also supported (portrait) |
Video models (video_model)
seedance-2 (default), veo-3.1, kling-3.0-pro, sora-2, sora-2-pro,
hailuo-2.3-std, wan-2.7, luma-ray2.
resolution: 480p / 720p (default) / 1080p · duration: seconds (default 5) ·
audio: boolean (default true; only some models support it).
Operations
Create — cosmiq_create
One image (optionally a video).
Generate an image from a prompt; optionally animate it to video. Returns a board (and a
video URL when withVideo).
| Param | Type | Notes |
|---|---|---|
prompt | string · required | What to generate |
space | string | Optional workspace to group the board under |
format | string | Aspect ratio (see above) |
image_model | string | Override the default image model |
withVideo | boolean | Also animate the image into a video |
video_model | string | See video models |
duration | number | Video length (s), default 5 |
resolution | string | 480p/720p/1080p |
audio | boolean | Generate audio with the video |
Campaign — cosmiq_campaign
Build 1–12 prompt → image concepts on a single board.
| Param | Type | Notes |
|---|---|---|
brand | string · required | Name used for the board title and its workspace |
concepts | array · required | { label?, prompt, reference_image_urls?[] (≤4) } |
reference_image_urls | string[] (≤4) | Shared references applied to concepts with none of their own |
generate | boolean | true = render now (credits); omit/false = leave ready (free) |
format | string | Aspect ratio |
image_model | string | Override image model |
Carousel — cosmiq_carousel
One board with a shared style wired into every slide, so all slides look consistent.
| Param | Type | Notes |
|---|---|---|
style_prompt | string · required | Shared look for all slides (background, layout, slide-number placement, fonts, palette) |
slides | array 2–15 · required | { label?, prompt } — one per slide |
brand | string | Optional workspace name to group the board under |
board_name | string | Board title |
format | string | Aspect ratio (default 4:5) |
generate | boolean | true = render slides now; omit = build graph only |
image_model | string | Override image model |
Add images — cosmiq_add_image
Put existing public image URLs onto a board as nodes (no generation, no credits).
| Param | Type | Notes |
|---|---|---|
image_urls | string[] 1–20 · required | Public image URLs |
space | string | Optional workspace to group the board under |
board_name | string | Board title (default “Images”) |
Edit — cosmiq_image_edit
Wire reference image URL(s) into an edit chain with an authored prompt (keep the real product, change the scene).
| Param | Type | Notes |
|---|---|---|
edit_prompt | string · required | The edit instruction |
reference_image_urls | string[] (≤8) | Public URLs of image(s) to edit |
space | string | Optional workspace to group the board under |
board_name | string | Board title |
generate | boolean | true = run the edit now (needs a reference); omit = build the graph only |
image_model | string | Override image model |
Read a board — cosmiq_get_board
Read an existing board to revise it: returns its prompt nodes (id + text) and the
board’s images as viewable content.
| Param | Type | Notes |
|---|---|---|
board | string · required | Board URL or id |
Update prompts — cosmiq_update_prompts
Rewrite the text of prompt nodes on an existing board (read-modify-write; other nodes and
edges preserved). Pair with cosmiq_get_board.
| Param | Type | Notes |
|---|---|---|
board | string · required | Board URL or id |
updates | array 1–30 · required | { node_id, text } per prompt to rewrite |
Response
Operations return links:
{
"board": "https://www.cosmiq.studio/boards/abc123",
"space": "Spring launch", // workspace the board was grouped under (if named)
"video": "https://.../clip.mp4" // only when a video was generated
}Open the board to refine prompts, regenerate, swap models, or download.
Notes & limits
- Reference images need public URLs to be wired into a chain.
- On-image label text may not be pixel-perfect (text-to-image limitation); references keep the product look, not always micro-typography.
- Rate/credit limits follow your plan.