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, and when Gen8 Flash (Preview) 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.

• Args: prompt (required, ≤ the account's promptMaxChars) · aspectRatio (1:1 default, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3) · quality / style (preset id or "auto") · negativePrompt · 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, 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, four ways: face-ref keeps a face identity across new scenes, character-ref keeps a whole character consistent, 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.

• Args: tool (required) · refCreationIds (required; strict caps — face/character-ref 1–6, style-transfer 1–3, smart-edit the image to edit plus up to 3 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 3 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 (≤3 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 Flash (Preview) (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 Flash the scenario: opening frame, shots in order, the sound) · inputCreationId (required; the opening frame on Gen8 Flash) · videoModel (default = Video, next = Gen8 Flash) · duration (Video: 5, 6 or 7 s, 7 is tier-gated, default 5 — recommended · Gen8 Flash: a length from get_account.videoDurationsNext, 1, 5, 8 or 10 at launch) · quality (enum auto … ultimate; Video: recommended ultra at 5 s, ultimate = 1080p · Gen8 Flash: a preset from get_account.qualities.videoNext, fast at launch) / style · refCreationIds (Gen8 Flash only: up to 6 references after the first frame — characters, props, places — each adds a surcharge) · aspectRatio (Gen8 Flash only: auto keeps the first frame's ratio) · audioCreationId + audioUse (Gen8 Flash 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 Flash 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) · hideFiled · random · 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_ALLOW_ANY_PATH=1.

• 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 Flash 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_ALLOW_ANY_PATH=1.

• 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.

• Args: creationId (preferred) or cdnId · savePath (confined to the working directory unless TWODAI_ALLOW_ANY_PATH=1).
• Returns: the written path, or an inline preview.
• 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.