Tools Reference

Tools Reference

All 24 tools, grouped the way agents use them. Every tool returns a human-readable summary line plus a structured JSON block, so both the model and any scripted consumer get what they need. Errors come back as tool errors with an actionable one-liner — never a crashed server.

Cost at a glance: only the five generate_* submission tools spend credit. Everything else — every read, upload, download, organise, publish and wallet tool — is free.

Group	Tools	Scope
Account & stats	get_account, get_stats	read
Generating	generate_image, generate_with_refs, generate_in_artistic_style, generate_video, generate_similar, generate_wallpaper, check_generation, cancel_generation	generate (checks: read)
Library & search	list_creations, browse_feed, get_creation, upload_image, download_creation	read (upload: generate)
Folders & organising	list_folders, list_artistic_styles, manage_folder, organise_creation	manage (listing: read)
Publishing	publish_creation	publish
Wallet (read-only)	get_wallet_status, get_lock, get_wallet_history, get_token_price	finance (price: read)

---

Account & stats

get_account

The connected account: available credit, tier, the API key's label, scopes and spend cap, every quality preset with the account's access (allowed or tier-locked) and the platform recommendation, plus the video durations with their locks. Agents are told to call this before proposing generations, to check there is headroom and the right scopes — and to read the presets here instead of probing them by submitting (a locked preset is refused at submit with a 403 and wastes a round-trip).

• Args: none.
• Returns: userId, username, creditUsd, tier, the key context (label, scopes, spentUsd, spendLimitUsd), qualities.image / qualities.video (id, name, description, allowed, recommended), videoDurations (value, locked, recommended), defaultVideoDuration, canUseVideo, canUseImageNext with qualities.imageNext (the Gen8 Preview images presets generate_image with imageModel: "next" may submit, allowed resolved), modelChannels (the engine behind each channel), and when Gen8 Preview video is open to the account qualities.videoNext, videoDurationsNext and defaultVideoDurationNext (the lengths and presets generate_video with videoModel: "next" may submit), plus a recommendation block (image max, video ultra at 5 s, ultimate = highest resolution, prompts ≤ promptMaxChars of the account, 1,500 to 20,000).
• Cost: free · scope read.

get_stats

One consolidated read of the account's activity: creation counts and streak, storage use, generation volume and spend over a window (split by day, tool and origin), plus the most-used references, styles and keywords. The first line is a ready-made summary; the JSON block has the detail. See Stats & Wallet for the full structure.

• Args: days — 30 (default) or 90.
• Returns: overview (storage, counters, streak, smart-collection counts, per-tool recents, cache freshness), generations (totals, by-day, by-tool, by-source), top (top refs / styles / keywords).
• Cost: free · scope read. Served from a server-side cache whose age is reported; a stale cache refreshes itself in the background.

---

Generating

All five submission tools share the same wait behavior: they block up to the wait budget (~45 s by default) and return the finished creation with an inline preview — or, if the job outlives the budget, a queueId to collect with check_generation. Pass wait: false for the ticket immediately. Full flows, retry semantics and NSFW notes: Generating.

generate_image

Text-to-image. Style and quality default to "auto" — the server picks by tier. Recommended quality: max (best balance of detail and price); ultimate for the highest resolution. imageModel: "next" runs Gen8 Preview images: up to 6 references kept natively, legible text, long literal prompts, priced on render time at roughly 4–7× the Gen 7.2 preset — Holder and up (get_account → canUseImageNext).

• Args: prompt (required, ≤ the account's promptMaxChars) · imageModel (default = Gen 7.2, next = Gen8 Preview images) · refCreationIds (up to 3, up to 6 with imageModel: "next"; strict — TOO_MANY_REFS uncharged; each adds a surcharge) · aspectRatio (1:1 default, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3) · quality / style (preset id or "auto") · negativePrompt (optional — applied by Gen8 Preview images, the Gen7 image engine renders without it) · allowNSFW · enhance · wait.
• enhance (default false): runs TIXI, the 2DAI prompt enhancer, before the image model. TIXI rewrites the brief in a fixed order — subject and action, positions relative to objects and enclosures, secondary elements, setting, style — which removes most scene-logic errors (a hand reaching through glass, a character inside the machine it operates). Turn it on for scenes with several elements or interactions; leave it off when the prompt is already precise and must be honoured verbatim. No extra credit, about 2 s of latency. Your text stays in prompt; the rewrite is what the model saw.
• Returns: queueId, status, creationId, viewUrl (the only shareable link — opens in the owner's 2DAI drive, login prompt if needed), costUsd, imageModel (when the job ran on a channel; next = Gen8 Preview images), startedAt (once a worker picked the job up), completedAt, width, height, nsfwRate (0..1), nsfwLabel (SFW / Suggestive / Near-nude / Adult NSFW / Prohibited), nsfwFlagged (only when true), description (vision-derived caption — withheld and replaced by descriptionHidden: true when nsfwRate ≥ 0.8; call get_creation for the caption if you need it) — plus an inline preview image. There is no downloadUrl or cdnId in the reply: bytes come through download_creation.
• Cost: spends credit · scope generate.

generate_with_refs

Image conditioned on existing creations, three ways, all on the Gen8 image engine: character-ref keeps a character consistent across new scenes (face shots, full-body shots or a character sheet; face photos lock the exact same face, the prompt drives outfit, pose and scene), style-transfer extracts the style of the refs and applies it to the prompt, smart-edit edits refCreationIds[0] following the prompt as the edit instruction. The former face-ref tool was merged into character-ref.

• Args: tool (required) · refCreationIds (required; strict caps — character-ref 1–6, style-transfer 1–6, smart-edit the image to edit plus up to 5 support refs) · prompt (required for smart-edit, optional for style-transfer) · aspectRatio · quality · allowNSFW · extractionDirective (style-transfer only, default "style") · wait.
• Returns: same generation summary + inline preview.
• Cost: spends credit · scope generate.

generate_in_artistic_style

Artist Painter: render the prompt as a new work in a curated artistic style — the subject is painted in the chosen style, unsigned unless the prompt asks for a signature. Up to 6 optional subject images anchor what gets painted.

• Args: prompt (optional when refCreationIds is given) · artisticStyleId (from list_artistic_styles, or "auto" — default — to let the server pick the best-matching style for the prompt) · refCreationIds (≤6 subject images) · aspectRatio · quality · allowNSFW · wait.
• Returns: same generation summary + inline preview; the creation carries artisticStyleName.
• Cost: spends credit (billed like style-transfer) · scope generate.

generate_video

Animate an existing still creation into a short clip — silent on Video, or with sound on Gen8 Preview video (videoModel: "next"). Costs several times an image and takes minutes, so it usually returns a queueId rather than the finished clip.

• Args: prompt (required — camera, motion, mood; on Gen8 Preview video the scenario: opening frame, shots in order, the sound) · inputCreationId (required; the opening frame on Gen8 Preview video) · videoModel (default = Video, next = Gen8 Preview video) · duration (Video: 5, 6 or 7 s, 7 is tier-gated, default 5 — recommended · Gen8 Preview video: a length from get_account.videoDurationsNext, 1, 5, 8 or 10 from Holder, up to 20 at Founder) · quality (enum auto … ultimate; Video: recommended ultra at 5 s, ultimate = 1080p · Gen8 Preview video: a preset from get_account.qualities.videoNext, fast from Holder, every preset at Founder) / style · refCreationIds (Gen8 Preview video only: up to 6 references after the first frame — characters, props, places — each adds a surcharge) · aspectRatio (Gen8 Preview video only: auto keeps the first frame's ratio) · audioCreationId + audioUse (Gen8 Preview video only: an MP3 from upload_audio as the audio reference — music = soundtrack / sound design, voice = a voice sample the speaking character follows; counts as one more reference; AUDIO_REF_NEXT_ONLY on the default model, INVALID_AUDIO_REF when the creation is not an audio file) · enhance (with style: "raw": TIXI writes the motion scenario or the full Gen8 Preview video brief from your idea, a prompt starting with tixi adds a thinking pass; every other style already runs TIXI and cannot switch it off) · frameInterpolation (Video only: 18 → 36 fps, twice the price) · allowNSFW · wait. The response carries the resolved quality, costUsd, videoModel, and on completion durationSeconds / fps.
• Returns: generation summary; the preview is a still frame of the clip. Save the mp4 with download_creation.
• Cost: spends credit · scope generate.

generate_similar

"More like this one" — the server re-derives the original tool's parameters (prompt, style, quality, dimensions, references) from the stored creation and submits a fresh generation. No parameters to reconstruct. Raw uploads and wallpaper outputs can't be re-derived and are refused.

• Args: creationId (required) · wait.
• Returns: generation summary + preview; the new creation records its parent.
• Cost: spends credit (usual price) · scope generate. Rapid identical calls within ~5 s are deduplicated server-side.

generate_wallpaper

Expand an existing creation into a wallpaper format — the original content is preserved and the surroundings are painted outward. Quality is fixed at Ultra (no quality knob); the dimension drives the price. Unknown dimensions are rejected, never priced at a default.

• Args: inputCreationId (required) · dimension (required: standard, photo, widescreen, ultrawide) · refCreationIds (up to 3 extra refs to steer the new areas) · prompt (optional guidance) · allowNSFW · wait.
• Returns: generation summary + preview.
• Cost: spends credit (by dimension) · scope generate.

check_generation

Takes one queueId, or queueIds (up to 25) to poll a batch of shots in one call — one line per job, finished ones hydrated, no inline previews in batch mode.

Look up a generation by the queueId returned when a generate_* call outlived its wait budget. Reports progress, and returns the finished creation (with preview) once it lands. Stored queueIds keep answering indefinitely — settled jobs are archived, not deleted.

• Args: queueId (required).
• Returns: the same generation summary as the submit tools.
• Cost: free · scope read.

cancel_generation

Cancel a generation that is still waiting in the queue — the charge is refunded and the slot freed. Once a worker has picked the job up it cannot be aborted; the tool then explains the current status instead (let it finish and collect it — a job that fails on its own is refunded automatically).

• Args: queueId (required).
• Returns: confirmation, or a too-late explanation with the current status.
• Cost: free (refunds on success) · scope generate.

---

Library & search

list_creations

Page through the account's creations, newest first — or pick one at random. Filter modes are mutually exclusive: a folder (folderId, "root" for ungrouped) / the trash / an activity lens / a smart collection / a folder shared with the account / a folder group (groupId). Cross-cutting filters combine with any mode. Full detail: Library & Drive.

• Args: limit (default 20, max 100) · beforeDate cursor or page · folderId · trashed · activity (all, history, uploaded, likes, public, trash, sdk, mcp, portfolio) · smart (faces, videos, crop, alpha, favorites) · sharedFolderId · groupId (a folder group — every folder filed in it) · search (whole-word AND; trailing * = prefix) · sort (newest default, oldest, updated, size-desc, size-asc, type-asc, type-desc) · ratioFilter (1-3 of square, landscape, portrait) · from / to (ISO 8601 dates or instants, UTC; a day alone includes that whole day) · likeFilter (liked, unliked — the account's own likes) · mediaKind (image incl. GIFs, video, audio; not audio with random) · blockNsfw · hideFiled · random (one creation from the same filtered set, images and videos only) · usedRef (creations built FROM a given creation).
• Returns: slim rows — creationId, prompt/description excerpts, toolKind, source, dimensions, folder, trash/public/like state, isOwner (only when false), nsfwFlagged / nsfwRate — plus a nextBeforeDate cursor when more rows exist.
• Cost: free · scope read.

browse_feed

Page through the 2DAI public feed — what creators across the platform have published, newest first. Rows belong to other accounts (isOwner: false, prompts hidden); your agent can like them with organise_creation. NSFW-flagged rows are excluded unless includeNsfw is set.

• Args: limit (default 12, max 24) · page · includeNsfw.
• Returns: slim rows + page, hasMore.
• Cost: free · scope read.

upload_image

Upload a local image (or base64 bytes) to the cloud drive so it can be used as a reference ("use THIS image"). Goes through the platform's moderation pass. Max 10 MB; jpeg/png/webp. Paths are confined to the working directory unless TWODAI_FILE_ACCESS=any; the hosted server has no filesystem — send base64 there.

• Args: path or base64 (one required) · filename · contentType (with base64) · targetFolderId (file it straight into a folder) · croppedFromCreationId / erasedFromCreationId (record the upload as a crop / erase edit of a creation you own — mutually exclusive).
• Returns: creationId, cdnId, dimensions, folderId, and nsfwFlagged when the moderation pass flagged it.
• Cost: free · scope generate.

upload_audio

Upload a local MP3 (or base64 bytes) to the cloud drive so it can be the audio reference of a Gen8 Preview video clip: pass the returned creationId as audioCreationId to generate_video with videoModel: "next", with audioUse: "music" (soundtrack / sound design) or "voice" (a voice sample the speaking character follows). MP3 only, 5 minutes max (400 AUDIO_TOO_LONG), Holder tier and up (403 AUDIO_NOT_ALLOWED). No vision caption — the file name and length label it; the row shows mediaKind: "audio" in listings. Paths are confined to the working directory unless TWODAI_FILE_ACCESS=any; the hosted server has no filesystem — send base64 there.

• Args: path or base64 (one required) · filename · targetFolderId (file it straight into a folder).
• Returns: creationId, cdnId, durationSec, label, folderId.
• Cost: free · scope generate; the reference itself adds one reference surcharge to the clip it is used on.

download_creation

Fetch a creation's media. With savePath the full-resolution asset is written to disk (extension appended automatically). Without it, a downscaled preview comes back inline so the model can look at the image — full bytes never go through the context window.

Hosted server (mcp.2dai.io) — no filesystem: savePath is refused, and the reply carries downloadUrl, the full-resolution file on the API. GET it with the same Authorization: Bearer header you send to the server (public creations need none). Videos have no preview: use the URL.

• Args: creationId (preferred) or cdnId · savePath (confined to the working directory unless TWODAI_FILE_ACCESS=any; not on the hosted server) · watermark (default true).
• Returns: the written path, or an inline preview — plus downloadUrl on the hosted server.
• Cost: free · scope read.

get_creation

Fetch a single creation row by id. Same slim shape as list_creations rows. Fills the gap left by list-only access, and doubles as the opt-in path for the vision-derived caption when a generation reply withheld it at the Near-nude+ NSFW tier.

• Args: creationId.
• Returns: { creation } — full slim row: creationId, viewUrl, prompt (owner-only), description, toolKind, source, width, height, folderId, inTrash, isPublicShared, likes, isLiked, isOwner (only when false), nsfwFlagged, nsfwRate, username.
• Cost: free · scope read.

---

Folders & organising

list_folders

Page through the account's folders (collections). Use a folderId with list_creations to see contents, or with organise_creation to move something into it.

• Args: limit (default 20, max 100) · beforeDate cursor · sort (index = the user's manual sidebar order, date-desc, date-asc, name-asc, name-desc, update-desc).
• Returns: folderId, title, shared flags, createdAt, plus a cursor.
• Cost: free · scope read.

list_artistic_styles

The curated artistic styles available to generate_in_artistic_style.

• Args: none.
• Returns: artisticStyleId, title, blurb (short public description), thumbnailUrl per style.
• Cost: free · scope read.

manage_folder

Folder CRUD plus sidebar organisation — one tool, ten actions.

• Args: action (required) + the fields that action needs:
  • create — title (+ optional description, groupId to create inside a group)
  • rename — folderId + title and/or description
  • delete — folderId; creations detach to the drive root by default, or go to trash with trashContents: true. Never a permanent delete.
  • set-favorite — folderId + favorite (starred folders feed the favorites smart collection)
  • set-poster — folderId + posterCreationId (a creation to pin as the folder cover, or "none" to clear)
  • move-to-group — folderId + groupId ("none" detaches)
  • create-group / rename-group — title (+ groupId for rename); groups are the collapsible sidebar sections
  • delete-group — groupId; only detaches its folders
  • list-groups — no args
• Returns: the affected ids and new state per action.
• Cost: free · scope manage (list-groups only needs read).

organise_creation

Move, trash, restore, delete or like creations.

• Args: action (required) + one of:
  • move — creationId + folderId ("root" detaches to the drive root)
  • trash / restore — creationId; trash is always reversible
  • like / unlike — creationId; sets the like state, so repeats are harmless, and public creations can be liked too
  • batch-trash / batch-restore — ids (up to 100 in one call)
  • delete — creationId; permanent, one creation per call by design, and only works on a creation already in trash
• Returns: confirmation per action; batches report processed/requested/skipped.
• Cost: free · scope manage.

---

Publishing

publish_creation

Flip one creation's public visibility. Publishing puts it on the 2DAI public feed. Only the account's own AI generations can go public — raw uploads and NSFW-flagged creations are refused by the platform. Unpublish always works on a public row. The tool is annotated so agents publish only when the user explicitly asked.

• Args: action (publish / unpublish) · creationId.
• Returns: confirmation.
• Cost: free · scope publish.

---

Wallet (read-only)

All four tools are strictly read-only — no tool on this server can move money. The first three need the opt-in finance scope; details and the scope's rationale are in Stats & Wallet.

get_wallet_status

$2DAI token balance, USD credit, and the account's effective tier with the four signals it derives from (explicit assignment, staking watermark, 24h hold watermark, live wallet value — the highest wins). Also flags any in-flight withdrawal, swap or staking lock.

• Args: none. · Cost: free · scope finance.

get_lock

Staking-lock status: none, active (with time remaining), or expiring-soon (under 24 hours left). Locks are managed in the dashboard, never here.

• Args: none. · Cost: free · scope finance.

get_wallet_history

Money history, four kinds: transactions (deposits, withdrawals, swaps — newest first, paged), balance ($2DAI chart points), credit (USD-credit chart points), sources (where credit came from and went: accrued, bonuses, swapped in, spent on generations).

• Args: kind (required) · limit (transactions: rows per page, 5–50, default 20; balance/credit: window in days, 7–365, default 90) · page (transactions, 0-based) · days (sources, default 30).
• Cost: free · scope finance.

get_token_price

The cached $2DAI/USD quote with its staleness. Never triggers a live refresh — treat it as indicative. Needs only read, not finance.

• Args: none. · Cost: free · scope read.