How to connect Sunra AI MCP with Python

Create a project in the user's Sunra account. Every generation lives on a project. project_url is the project's page in the Sunra web app, where the user sees its results; the web app's sidebar also lists projects under Recents and Projects.

The caller's own projects, most recently updated first. project_url opens each one in the Sunra web app.

Create a downloadable GLB on a project. Supports the text and image inputs offered by the model catalog. Meshy image input can take a texture prompt; Tripo image input takes no text. Catalog defaults apply. Stages a model node and quotes credits; confirm_execution starts it. auto_confirm=true spends immediately. Read results with get_job, wait_for_nodes, or inspect_node. Running generations are capped per plan, by type and in total; get_balance and estimate_cost show how many can start. A task over the cap is refused: wait for running ones with wait_for_nodes, then send the rest, instead of retrying at once.

Generate images on a project with models such as FLUX, GPT Image, Nano Banana, Seedream, Midjourney, Ideogram, Krea and Grok Imagine (model ids from list_models). count is how many images, the same number as the web quantity control. Omit count for one task. The credit total is the price of one task times the number of tasks. A model that returns several images per task snaps count onto whole tasks, and the result says how many images that is. A count above the model limit is an error. Stages one node per task and returns the total estimated credit cost. Pass auto_confirm=true to spend immediately. Otherwise call confirm_execution once, with any returned plan_id, to start every task from this request. Use wait_for_nodes for the output URL. Lands on the Project tab (asset list), not a timeline. Running generations are capped per plan, by type and in total; get_balance and estimate_cost show how many can start. A task over the cap is refused: wait for running ones with wait_for_nodes, then send the rest, instead of retrying at once.

Generate speech, sound effects, music, dialogue, a voice change, or a dub on a project. Same spend gate as create_image. model is one of the audio models from list_models type=audio. Use list_voices for voice names. A voice is rejected before staging when it is not legal for that model. Running generations are capped per plan, by type and in total; get_balance and estimate_cost show how many can start. A task over the cap is refused: wait for running ones with wait_for_nodes, then send the rest, instead of retrying at once.

Generate videos on a project with models such as Kling, Veo, Seedance, FLUX, Wan, MiniMax, Grok Imagine and Happy Horse (model ids from list_models). count is how many videos, the same number as the web quantity control. Omit count for one video. The credit total is the price of one video times count. A count above the model limit is an error. One confirm_execution on any returned plan_id starts every video from this request. Pass auto_confirm=true to spend immediately. Lands on the Project tab, not a timeline. Choose the input with start_image, end_image, reference_images, reference_videos, reference_audios, or source_video. image_urls is the old compatibility field and is ignored when any of those is set. seedance-2.5 at 480p with a fixed duration is a preview unless draft is false. The preview price matches a standard 480p video. Pass draft_source_task_id (our preview task id) to make a separate 1080p final at the 1080p price. Or pass the task_id of a finished Pika H3 Flex 480p or 768p video as draft_source_task_id, with resolution 1080p, 2k or 4k, to upgrade that video; the charge is only the price difference per second of the source. A final or an upgrade is one video. Running generations are capped per plan, by type and in total; get_balance and estimate_cost show how many can start. A task over the cap is refused: wait for running ones with wait_for_nodes, then send the rest, instead of retrying at once.

Models this key can generate, from families such as image: FLUX, GPT Image, Nano Banana, Seedream, Midjourney, Ideogram, Krea, Grok Imagine; video: Kling, Veo, Seedance, FLUX, Wan, MiniMax, Grok Imagine, Happy Horse; audio: ElevenLabs, Suno, MiniMax; 3D: Meshy, Tripo. This live list is authoritative; pass its model_id as model. type=audio lists the web audio models only. type=model3d lists supported 3D models. Omit type for image, video, and 3D. Does not include prices. requires_subscription true means the model needs an active Sunra plan; get_balance's subscriptionAllowance.isActive says whether the user has one.

Active named voices for text-to-speech, voice-changer, and dialogue. Each voice includes modes: tts, voice-changer, and/or dialogue, matching the web picker for that mode and provider. mode=tts lists every TTS provider: pass provider=elevenlabs for elevenlabs-tts, provider=minimax for minimax-tts, and provider=heygen for heygen-voice-1 and heygen-voice-1-turbo. Omit mode to return every active voice with its modes. mode=voice-changer uses the Sunra 21 named ElevenLabs voices, including Harry, Bella, and Adam; no synthetic names are added. preview_url may be empty. provider still filters, such as elevenlabs or minimax. Pass name back as voice only for a mode that lists it.

Legal inputs for one catalog model (aspect ratios, durations, resolutions, reference image and video limits). Does not include prices. Reference image count follows max_ref_images, but some video routes take fewer (see create_video reference_images). max_ref_videos is the catalog cap for reference_videos. When present, reference_image_rules, reference_video_rules and reference_audio_rules are the file size, dimension, aspect ratio, length and format limits the model enforces on those inputs, duration_range is the accepted length and step for sound effects, and max_source_video_seconds caps a source video. Check inputs against them before creating; a file outside them makes the job fail.

Look up one generation job by task_id. Own jobs only. Also writes completed results or failure status back to the job's canvas node. Every job has draftFinalize (eligible, reason, expiresAt, finalizedTaskId); only a finished seedance-2.5 preview, or a finished Pika H3 Flex 480p or 768p video (then upgrade gives its source resolution and seconds), can be eligible. That object never includes an upstream draft id. A failed job may have error_reason and error_hint, which say what was wrong with the input and how to fix it; follow error_hint before retrying.

Cancel a pending or processing job. Credits are refunded through the same path as the web app. Own jobs only.

Presigned PUT for a local reference file. PUT the bytes to upload_url with the returned headers (the signature covers Content-Type), then pass asset_url as an image or video input, or as create_audio source_url for voice-changer and dubbing.

Spend credits and start a staged create_image, create_video, create_audio, or create_model3d. plan_id is any node_id from that create. One confirm starts every task from that create that has not started yet. A failed or cancelled task runs again and is charged again; running or finished tasks are not charged twice. estimated_credits in the result covers every task in the create, including ones already started. Do not confirm each image separately.

Wait for up to 10 nodes to get output URLs. Each call returns within about 55 s. If a node is still generating, the result has still_running=true. That is not an error: call wait_for_nodes again with pending_node_ids, or call get_job later. Video usually needs several calls. Split larger batches across calls. Start every task before waiting. Pass every node from one request in a single call. Output URLs are the files themselves. Also repairs missing completed results and writes failure status on the requested canvas nodes. A failed node may have error_reason and error_hint, which say what was wrong with the input and how to fix it; follow error_hint before retrying.

Read one generation node: status, prompt, output URLs. Also repairs missing completed results on that canvas node.

Show finished results to the user in the Sunra viewer, an in-chat gallery with Download, Copy and Use as reference. A last resort: call it only when you cannot show the images yourself. If your app can show files or images, or you can put a batch in a contact sheet or side-by-side, do that instead. Pass every node from one request in one call (up to 10), so they show together. Nothing is generated or charged. Also repairs missing completed results and writes failure status on the requested canvas nodes.

Look up an image that already belongs to the project (by node_id or image_url) and return its URL, width and height (recorded, or probed from our storage), and its node or file fields. Does not run a new generation.

Return the connected Sunra account: id, email and displayName. Email and displayName can be null. The account comes only from the verified OAuth identity; this tool cannot look up another account.

The user's real spendable credit balance. availableBalance already includes any active subscription allowance. This is the number you may quote. It leaves out today's free daily credits until they are granted, at the day's first generation or web app visit. Read it for the first reply after the user connects or says hi: two or three short lines, no list, with availableBalance, what Sunra makes (images, video, audio, 3D) and one thing to try that works where you run; plan notes can wait. availableBalance = subscriptionAllowance.remaining + topupBalance + rewardBalance - frozenAmount. totalBalance is the wallet only (topupBalance + rewardBalance) and leaves out the subscription allowance, so never present it as the total. If you list the parts, include frozenAmount: those credits are on hold and cannot be spent. subscriptionAllowance.cycle is how often the plan refreshes (monthly for web plans, weekly for app plans, sandbox for test purchases that refresh within minutes, mixed when more than one applies). Say when it renews from refreshesAt; do not call it a weekly allowance unless cycle is weekly. lowBalance is true below 200 available credits, and then note says in one neutral line how many are left and that plans and top-ups are at upgradeUrl. Tell the user once, not in every reply. concurrency is how many generations the plan runs at once: limits, running and remaining for image, video, audio and total (3D counts toward the total only); null when it could not be read. How credits work: Sunra gives free daily credits. A plan's credits refresh every cycle and do not roll over; the web plans are Basic (1,200 credits a month), Pro (from 3,500) and Creator (from 17,000). Top-ups are one-time credit purchases at list price, for subscribers only. Plans and top-ups are bought at upgradeUrl, which lists current plans and prices; this server cannot buy them. Models with requires_subscription (currently the video models) need an active plan, and subscriptionAllowance.isActive says whether the user has one.

Price an image, video, audio, or 3D generation before running it, in credits. For images and videos, count uses the same task count and the same limit as create_image and create_video. The total is one task times that count. Audio ignores count. Audio still uses the same units as a web audio task. Browsing prices is free. For image quotes, external reference images are downloaded and copied to Sunra storage, even when no generation is started. concurrency.can_start is how many generations of this type can start at the moment, and concurrency_note appears when this request has more tasks than that.