API and MCP reference

Studio has an authenticated HTTP API and a hosted read-only MCP server. An organization API key and an assistant connection have different permissions. Keep an organization key on your server.

API address and authentication

The API under the Studio app is https://app.cloutlabs.co/studio/v1. Account → API & MCP → API displays the current API base URL and links to Open API documentation.

The interactive reference is at Studio API documentation; the schema is at OpenAPI JSON.

An integration uses its workspace’s organization key as Authorization: Bearer authentication. Keys are scoped to that organization. Use a key supplied for your integration; the read-only key created in AI assistants is not a generation key.

This read example uses an environment variable rather than putting a key into a script:

curl --fail --silent --show-error \
  -H "Authorization: Bearer $STUDIO_API_KEY" \
  'https://app.cloutlabs.co/studio/v1/models'

Main endpoints

Paths below are relative to the API base ending in /v1. Read the live schema before implementing writes or the larger workflow payloads.

The storyboard planning endpoints remain separate from rendered Carousel Studio sets. For video, editing, batches, carousels, workflows, posting and connectors, the OpenAPI reference provides the complete endpoint families and schemas. Do not treat the short table as a replacement for those payload definitions.

Video and production endpoints

Video model identifiers are scail-2, wan-3.0, wan-3.0-prime, seedance-2.5 and heygen-video-1. A video plan distinguishes performance (motion or dialogue), mode (faithful, reinterpret or original), source_video, condition_on_source, creator, starting_frame, duration, resolution, aspect_ratio and audio (preserve_source, generate or silent). The count range is 1–4.

The full-generation request also requires request_key and expected_micro_usd. The request key is 16–64 letters, numbers, underscores or hyphens. Quote the chosen setup and follow the current schema before submitting it; do not guess a price or reuse settings from another workflow.

Revisioned edits and idempotent paid submissions have different concurrency rules. Read the endpoint’s required revision or request key, preserve a local edit on conflict, and inspect the existing record after an interrupted response.

Image generation request

POST /generations accepts these fields. Use the image catalog identifiers for model.

The queued response includes id, thread_id, creator, model, modelName, prompt, params, status, images, error, microUsd, credits, secs, requestedAt, startedAt and finishedAt.

Statuses are queued, running, succeeded, failed and cancelled. Each result image has key, url, w, h, seed and an optional model. Poll the returned identifier to read completion. A 202 response means accepted, not finished.

GET /generations accepts creator, limit and before. The default limit is 60, with a range of 1–200. Use the oldest record’s requestedAt as the before timestamp for the next page.

POST /uploads returns id, url, w and h. Reference files are limited to 25 MB. Use the returned identifier in attachments, not the file’s URL.

Hosted MCP connection

Open Connectors → AI assistants. The hosted address is:

https://mcp-studio.cloutlabs.co/mcp

Add that address in an MCP client that supports HTTP and OAuth. Complete the Clout consent page for the workspace you intend to expose. The consent screen identifies the client, team and redirect destination.

The connection is pinned to that team. Switching your active workspace later does not silently move the assistant connection to another team.

The published tool set contains nine read tools. An assistant can read Studio; it cannot generate, post, spend credits, delete or edit content. Use Disconnect on the connection to revoke it.

For a client that takes an authorization header instead, select Other, enter Key name and choose Make a key. The read-only key is shown once. Store it securely and send it as a Bearer header. Do not put the value into prompts, screenshots or shared configuration files.

MCP tools

Errors and integration safety

Keep write integrations server-side. Check the existing job after a connection interruption before submitting paid work again. For carousel planning, request_key identifies a submission: repeating it with the same payload reuses the job; different settings with that key return 409.