Repository navigation
Generating
Everything here spends your account's real credit — the same credit the
studio uses. The server tells agents to check get_account first when unsure
and never to generate speculatively, but the best guardrails are yours: a
per-key spend cap (set at mint time) and asking for one image before asking
for ten.
Finished images come back with an inline downscaled preview, so your
agent can look at what it made and iterate — full-resolution bytes only ever
go to disk via download_creation.
Generate a 16:9 image of a neon city street after rain, cinematic.
That's generate_image. Style and quality default to "auto" — the server
picks sensible presets for your tier — and the agent can pass a
negativePrompt for things to avoid. Aspect ratios: 1:1 (default),
16:9, 9:16, 4:3, 3:4, 3:2, 2:3. Prompts are capped per account tier, 1,500 to 20,000
characters (get_account → promptMaxChars).
Which quality? The ladder is the same for every tool — fast, normal,
high, max, ultra, ultimate. The recommended everyday pick is max
(the best balance of detail and price); ultimate is the highest
resolution, for final masters; fast and normal are for drafts. ultra and
ultimate are tier-gated: get_account lists which presets the connected
account may submit, so the agent never has to probe.
generate_image also takes up to 3 refCreationIds as soft guidance
(characters, products, places the picture should follow); each reference
adds a surcharge.
Make a concert poster titled "NEON TIDE": the singer from my portrait on the stage of the venue shot, bold white typography, rain and neon.
generate_image with imageModel: "next" runs Gen8 Preview images, the preview
of 2DAI's next image engine. It keeps up to 6 refCreationIds natively
(3 on the default model) — characters, products, places that stay
recognisable — renders legible text in the picture and honours long, literal
prompts: describe the scene plainly, refer to each reference by what it
shows ("the singer with the red braids", "the neon-lit stage") — never by its
position ("the second reference") — and avoid keyword lists. The quality ids are the same (auto follows the
default model's tier rule — from Holder, a weighted draw over max / ultra /
ultimate among the presets the tier may submit), each preset priced on render time (roughly four to seven times the Gen 7.2 price), and every reference
adds a surcharge on both models — costUsd on the reply is the truth. The
channel opens at Holder: get_account reports canUseImageNext and
qualities.imageNext (same ids, allowed resolved for the account and the
key's channel policy), so read them there, never probe; below the gate the
submit is refused uncharged with the tier that opens it. Finished creations
are stamped aiModel: "gen8.0" with imageModel: "next", and
generate_similar on such a row re-runs it on Gen8 Preview images. The other image tools
(generate_with_refs, generate_in_artistic_style, generate_wallpaper)
stay on Gen 7.2 for now.
generate_with_refs covers the three reference tools, all rendered on the Gen8
image engine. Reference ids come from
earlier generations, upload_image, or list_creations — so flows compose
naturally:
Upload
./me.jpg, then generate a portrait of that person as an astronaut on the moon.
(upload → character-ref, keeping the exact same face across a new scene)
Take my most recent creation and put the character in a winter forest.
(list → character-ref again, keeping the whole character consistent — 1–6 shots: face photos, full-body shots or a character sheet)
Generate a fox in the same style as this painting.
(style-transfer — the refs are the STYLE source, extracted and applied to
the prompt; an optional extractionDirective narrows what to extract)
Remove the crowd in the background of that image, keep the lighting.
(smart-edit — the first ref is the image to EDIT, the prompt is the edit instruction, and up to 5 more refs can ride along as visual support: a logo to insert, a garment to borrow…)
| Tool | Max refs |
|---|---|
generate_image (refCreationIds) |
3 · 6 with imageModel: "next"
|
character-ref |
6 |
style-transfer |
6 |
smart-edit |
6 (refs[0] = the image to edit) |
generate_wallpaper extra refs |
3 |
Exceeding a cap rejects the call before anything is charged — extras are never silently dropped.
Animate that image — slow camera push-in, gentle parallax.
generate_video animates an existing still creation into a clip of 5, 6
or 7 seconds (7 is tier-gated; default 5). Video costs several times
an image and takes ~1–3 minutes, so it usually hands back a ticket rather
than the finished clip — see the wait behavior below. The preview attached
on completion is a still frame; the mp4 itself goes to disk via
download_creation.
The recommended shot is ultra at 5 seconds — the best coherence for the
price. Clips run at 18 fps natively (frameInterpolation doubles it to
36 fps for twice the price). Subject identity holds for roughly the first
2.5–3.5 s, so write the cut at ~3 s, keep one action per shot, and prefer
several 5-second shots over one long take. ultimate is 1080p with the
longest wait. Price = tool base × preset × duration multiplier (1 / 1.3 /
1.5) × 2 with interpolation; auto draws the preset (max / ultra only for
video — never ultimate, ask for it explicitly), so pin it for a predictable
cost — every submit returns the resolved quality with costUsd.
Make a 10-second clip with sound: open on the beach shot, the surfer from my portrait lands the kite and waves at the camera, gulls and surf in the audio.
generate_video with videoModel: "next" runs Gen8 Preview video, the preview
of 2DAI's next video engine. Clips come out with sound, from a first frame
(inputCreationId) plus up to 6 refCreationIds — characters, props and
places that stay consistent through the clip (each adds a surcharge) — with
an optional aspectRatio (auto keeps the first frame's ratio;
frameInterpolation does not apply). Lengths and presets follow the
account: fast quality and 1, 5, 8 or 10 s from Holder, every preset and
12, 15, 17 or 20 s at Founder — get_account lists them as videoDurationsNext
and qualities.videoNext, so read them there, never guess; a length or
preset the account may not submit is refused with a 403 before any charge.
Every video style except raw (and auto) runs TIXI on the prompt and cannot
switch it off — the style guidance only exists through that rewrite. style: "raw"
sends the prompt verbatim; add enhance: true to have TIXI write the motion
scenario (Video) or the full Gen8 Preview video brief from a short idea, and start the
prompt with tixi for a thinking pass (the word is dropped from what TIXI reads).
Price follows the length (8 s ≈ 1.6×, 10 s ≈ 2×, 20 s ≈ 4× the 5 s price), +33 % per
reference after the first frame, the audio reference included.
A 1 s clip carries almost no sound. Long clips render for several minutes:
expect a queueId and collect it with check_generation. The prompt is the
scenario — name the opening frame, the shots in order and the sound you
expect. The clip can follow an audio reference of the account: upload_audio
an MP3 (5 min max, Holder+) and pass it as audioCreationId with audioUse: "music" (soundtrack / sound design) or "voice" (a voice sample the speaking
character follows) — it counts as one more reference for the price, and TIXI
writes the scenario around it when it runs.
Upload
./theme.mp3, then make an 8-second Gen8 Preview video clip from the stage shot with it as the soundtrack: the band walks on as the intro swells.
I love this one — make three more like it.
generate_similar re-runs an existing creation: the server re-derives
the original parameters (prompt, style, quality, dimensions, references)
from the stored creation, so there is nothing to reconstruct and nothing to
get subtly wrong. Charged at the usual price; the new creation records its
parent. Two kinds of rows can't be re-derived and are refused: raw uploads
(nothing was generated) and wallpaper outputs (their pricing dimension isn't
stored).
Turn this into an ultrawide wallpaper, extend the sky.
generate_wallpaper expands a creation into a wallpaper format — the
original content is preserved and the surroundings painted outward.
Dimensions: standard, photo, widescreen, ultrawide; the dimension
drives the price, and quality is fixed at Ultra. An optional prompt and up
to 3 extra refs steer the newly painted areas.
Generation times range from ~10 s for a fast image to ~3 minutes for video — but MCP hosts impose tool-call timeouts. The server resolves that tension with an adaptive wait:
- Under the wait budget (45 s by default,
TWODAI_WAIT_BUDGET_MS), the tool feels one-shot: it blocks and returns the finished creation. This is the common case for images. - Over the budget, it degrades gracefully: you get a
queueIdand an explicit next step instead of a hung call. The job keeps running server-side.
Still running after the wait budget — this is normal for video and high-quality images. Call check_generation with queueId "…" to collect it.
check_generation is free, reports progress, and returns the finished
creation (with preview) once it lands. Old queueIds keep working
indefinitely — settled jobs are archived, never deleted. Agents can also
pass wait: false to any generate tool to get the ticket immediately and
keep working while the job runs.
The one rule: collect with check_generation, never re-submit — a
re-submitted prompt is a new generation and a new charge.
Transports hiccup, and hosts retry. Two layers make that safe:
-
Client idempotency — each submit carries a token that is stable for
identical arguments within a ~30 s window (
TWODAI_IDEMPOTENCY_WINDOW_MS). A host retry of the same call inside the window is refused by the API as an idempotent retry — never charged twice — with a pointer to find the original viacheck_generationorlist_creations. The same request minutes later is simply a new generation, as it should be. -
Server dedup on
generate_similar— the server rebuilds the submit from the stored creation, so its own ~5 s dedup window is the authority there.
Actually, cancel that video.
cancel_generation withdraws a job that is still waiting in the queue:
the charge is refunded and the slot freed. Once a worker has picked the job
up there is no abort — the tool says so, with the current status, and the
race is benign either way: you cancelled in time and were refunded, or the
generation completes and you keep it. A generation that fails on its own is
always refunded automatically.
Adult content is governed by your account-level settings on 2dai.io, not
by this server. Each generate tool takes an allowNSFW flag, which works
only where the account permits it; prompts that moderation blocks come back
as a clear tool error. Creation rows surface nsfwFlagged and nsfwRate on
purpose, so hosts and agents can apply their own safeguards on top of the
platform's — and NSFW-flagged creations can never be published to the public
feed.