Everything the SDK does is plain HTTP — use it from Python, Go, Rust, curl or anything that speaks JSON. This page is the raw contract; if you're on JavaScript or TypeScript, the SDK wraps all of it (polling, retries, typed errors) and you can skip this.

• Base URL — https://dapp.2dai.io:444/v1
• Auth — Authorization: Bearer 2dai_sk_<keyId>_<secret> on every request. Header only; there is no query-param or cookie fallback.
• Content type — application/json except POST /v1/uploads (multipart/form-data).
• User-Agent — optional, but it decides how your creations are labelled. See below.

Get a key in the dashboard: Integrations → API keys. See Keys & Scopes for the scope matrix and spend caps.

Every creation carries a source, and the dashboard uses it to file your work: Cloud Drive → Activities has an SDK collection and an MCP collection, and the lightbox shows a matching origin pill. The server derives source from your User-Agent.

curl -X POST https://dapp.2dai.io:444/v1/generate/image \
  -H "Authorization: Bearer $TWODAI_API_KEY" \
  -H "User-Agent: 2dai-cloud-sdk/2.1.0" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a lighthouse at dusk"}'

Omitting it is fine — nothing is gated on the header. The request succeeds, the generation runs, you are charged the same. You simply land as api instead of sdk, which is the honest label for a raw REST caller anyway. Send the SDK token only if you genuinely want your traffic grouped with the SDK's.

The token must be a whole name/version word with a full x.y.z version. These do NOT match, and fall back to api:

2dai-cloud-sdk            ← no version
2dai-cloud-sdk/2.0        ← not x.y.z
2dai-cloud-sdk-fork/2.0.2 ← different name
my-app (uses 2dai-cloud-sdk)

Matching used to be a loose substring search, which mislabelled anything merely mentioning the name; it is strict as of the 2026-07-29 API build. This is attribution, never authorisation — no scope, quota or price depends on it, and forging a token only mislabels your own work in your own drive.

A generate call does not return an image. It returns a queueId; you then poll GET /v1/queue/:queueId until status is completed, at which point the row carries creationId, outputCdnId and downloadUrl.

# 1 · submit
curl -X POST https://dapp.2dai.io:444/v1/generate/image \
  -H "Authorization: Bearer $TWODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a lighthouse at dusk","width":1456,"height":816}'
# → {"queueId":"a1b2…","status":"pending","costUsd":0.07}

# 2 · poll until completed
curl "https://dapp.2dai.io:444/v1/queue/a1b2…" \
  -H "Authorization: Bearer $TWODAI_API_KEY"
# → {"queueId":"a1b2…","status":"completed","creationId":"…","downloadUrl":"/cdn/file/…"}

# 3 · fetch the bytes (same bearer)
curl -L "https://dapp.2dai.io:444/cdn/file/<outputCdnId>" \
  -H "Authorization: Bearer $TWODAI_API_KEY" -o out.jpg

Poll every 2 s or so. Terminal statuses: completed, failed, cancelled, timeout, expired, dismissed. Non-terminal: pendingCharge, pending, processing. A job waiting for render capacity stays pending (it can also go from processing back to pending) — keep polling.

A failed, timeout or expired job also returns errorCode (a stable code to branch on) and errorMessage (a readable sentence to show), next to the raw error:

{ "queueId": "a1b2…", "status": "failed", "error": "GENERATION_FAILED: …",
  "errorCode": "CAPACITY_FULL",
  "errorMessage": "No capacity left right now. You weren't charged — try again soon." }

The codes are listed in Errors → Why a generation failed.

Every error is JSON with an error code, sometimes plus context fields:

{ "error": "KEY_SPEND_LIMIT_REACHED", "costUsd": 0.07, "spentUsd": 5, "spendLimitUsd": 5 }

Three can come back from any endpoint:

Per-endpoint codes are listed below. Error Handling maps them to the SDK's typed classes.

JSON responses omit keys whose value is undefined — treat every optional field as "may be absent" rather than "may be null".

No parameters.

{
  "userId": "0029e8ae…",
  "username": "2DAI",
  "creditUsd": 99855.65,
  "tier": "tier5",
  "canDisableWatermark": true,
  "quality": { "ultraImage": true, "ultraVideo": true, "ultimateImage": true, "ultimateVideo": true },
  "qualities": {
    "image": [ { "id": "max", "name": "Max", "description": "Recommended · …", "allowed": true, "recommended": true }, … ],
    "video": [ { "id": "ultra", "name": "Ultra", "description": "Recommended · 800p · …", "allowed": true, "recommended": true }, … ],
    "videoNext": [ { "id": "fast", "name": "Fast", "allowed": true, "recommended": false }, { "id": "high", "name": "High", "allowed": true, "recommended": true }, … ],
    "imageNext": [ { "id": "max", "name": "Max", "allowed": true, "recommended": true }, … ]
  },
  "videoDurations": [ { "value": 5, "label": "5s", "locked": false, "recommended": true },
                      { "value": 6.5, "label": "6s", "locked": false }, { "value": 7.5, "label": "7s", "locked": true } ],
  "defaultVideoDuration": 5,
  "canUseVideo": true,
  "videoDurationsNext": [ { "value": 1, "label": "1s", "locked": false }, { "value": 5, "label": "5s", "locked": false, "recommended": true },
                          { "value": 8, "label": "8s", "locked": false }, { "value": 10, "label": "10s", "locked": false }, … ],
  "defaultVideoDurationNext": 5,
  "canUseImageNext": true,
  "modelChannels": { "video": { "default": "gen7", "next": "gen8" }, "image": { "default": "gen7", "next": "gen8" } },
  "promptMaxChars": 4000,
  "promptMaxCharsNext": { "tier": "Believer", "max": 6000 },
  "key": { "keyId": "5zmvg7rj", "label": "E2E Tests",
           "scopes": ["read","generate","manage","publish"],
           "spendLimitUsd": null, "spentUsd": 1.36,
           "modelChannels": ["default", "next"] }
}

spendLimitUsd: null means uncapped. Your account credit is always the real limit. qualities carries every preset per generation type with the tier lock resolved (allowed) and the platform recommendation (recommended: image max, video ultra); pick from it instead of discovering locks with a 403 at submit. videoDurations[].locked and defaultVideoDuration follow the same idea. Gen8 Preview video — videoModel: "next" on the video endpoint — adds qualities.videoNext, videoDurationsNext and defaultVideoDurationNext when the engine is open to the account (video from Holder); Gen8 Preview images — imageModel: "next" on the image endpoint — is announced by canUseImageNext (the engine is on, the tier opens it — Holder — and the key reaches next) and qualities.imageNext (always listed, every preset allowed: false while the channel is off or locked); modelChannels names the engine behind each channel.

All three submit endpoints return the same shape:

{ "queueId": "…", "status": "pending", "costUsd": 0.07 }

costUsd is present only when the call was charged.

Endpoint-specific errors: 400 IMAGE_MODEL_UNAVAILABLE (the next engine is off), 403 TOOL_NOT_ALLOWED_FOR_TIER (tool: "image-next" below Holder), 403 KEY_POLICY_CHANNEL (the key's policy stops at default), 403 QUALITY_NOT_ALLOWED_FOR_TIER.

Every tool caps its reference list, and the caps are enforced strictly: exceeding one is a 400 { "error": "TOO_MANY_REFS", "max": …, "got": … } before any charge, rather than a silent trim.

There is no enhanced field here: character-ref always runs TIXI server-side (their directives are built around it), so expect the same ~2 s of prompt-rewriting latency whether you ask for it or not. Style-transfer runs a two-step TIXI pass of its own.

Endpoint-specific errors: 400 INVALID_TOOL, 400 REFS_REQUIRED, 400 TOO_MANY_REFS (with max / got), 403 TOOL_NOT_ALLOWED_FOR_TIER, 400 INVALID_EXTRACTION_DIRECTIVE.

Wallpaper-resize: expand a stored creation into a wallpaper dimension.

Quality is forced to Ultra server-side (there is no quality field), same as the studio's tool. Endpoint-specific errors: 400 INPUT_CREATION_REQUIRED, 400 MISSING_DIMENSION, 400 TOO_MANY_REFS.

Endpoint-specific errors: 400 INPUT_CREATION_REQUIRED, 400 INVALID_INPUT_CREATION_ID, 400 INVALID_DURATION, 400 TOO_MANY_REFS, 400 VIDEO_MODEL_UNAVAILABLE (the next engine is off), 403 INSUFFICIENT_TIER (a length above the tier), 403 QUALITY_NOT_ALLOWED_FOR_TIER (a preset above the tier), 400 AUDIO_REF_NEXT_ONLY / 400 INVALID_AUDIO_REF / 400 AUDIO_TOO_LONG (the audio reference).

Body: { "creationId": "…" }. The server re-derives the original tool's submit from the stored row (prompt, style, quality, dimensions, references) and queues it like any other generation — same ticket response, same pricing, same gates, and the per-key spend cap applies. The new creation records its parent in retriedFromCreationId.

Endpoint-specific errors: 400 MISSING_CREATION_ID, 404 CREATION_NOT_FOUND (unknown, not yours, or deleted), 400 CREATION_UNAVAILABLE (in trash), 400 REGEN_UNSUPPORTED_TOOL (raw upload or wallpaper-resize row), 400 REGEN_MISSING_SOURCE / 400 REGEN_MISSING_PROMPT (the stored row lacks what the tool needs), 422 REGEN_REFS_UNAVAILABLE (a character-ref row whose identity references are all in the trash, deleted, or no longer visible).

Every submit answers { queueId, status: "pending", quality, costUsd? } — quality is the preset the server resolved (what auto chose, and what costUsd was priced on).

• 404 CREATION_NOT_FOUND { missingCreationIds } — an inputCreationId, refCreationIds entry or extraction ref names a creation that does not exist, or a picture reference that is in the trash, deleted, or not visible to the account (neither yours nor public). Refused before any charge.

Both credit errors fire before any charge.

{
  "queueId": "…", "status": "completed", "costUsd": 0.07,
  "creationId": "…", "outputCdnId": "…", "downloadUrl": "/cdn/file/…",
  "createdAt": "…", "startedAt": "…", "completedAt": "…"
}

startedAt appears once a worker picked the job up (absent while it waits); imageModel / videoModel echo the channel when the job ran on one.

error carries the failure reason on failed rows; videoModel / imageModel name the channel ("next" = Gen8 Preview video / Gen8 Preview images) when the job was submitted on one. 404 QUEUE_ITEM_NOT_FOUND if the id is unknown or belongs to someone else.

Settled rows past your newest ~200 are eventually moved to an archive (never deleted); this endpoint reads the archive transparently, so a stored queueId keeps resolving with its terminal status and creationId.

Stop a generation that is still pending — the charge is refunded and the queue slot released:

{ "queueId": "…", "status": "cancelled" }

Once a worker has picked the job up there is no abort hook: 409 { "error": "NOT_PENDING", "status": "processing" } with the current status. The race is benign — either you cancelled in time and were refunded, or the generation completes and you keep it. 404 QUEUE_ITEM_NOT_FOUND for unknown ids, 403 when the item isn't yours.

The full listing engine — the same lenses and filters the studio's cloud drive uses. POST /v1/creations mirrors it exactly with the params in a JSON body, for when you'd rather keep search text out of URLs and proxy logs.

Modes — pick at most one; combining two is a 400 { "error": "CONFLICTING_FILTERS" }:

Cross-cutting params — compose with any mode:

{
  "creations": [{
    "creationId": "…", "prompt": "…", "description": "…",
    "toolKind": "image-gen", "style": "…", "quality": "high", "aiModel": "gen7.2",
    "outputCdnId": "…", "downloadUrl": "/cdn/file/…",
    "width": 2048, "height": 2048,
    "mediaKind": "image", "hasAudio": false,
    "isUploaded": false, "source": "sdk", "creationDate": "…",
    "folderId": "…", "inTrash": false, "isPublicShared": false,
    "likes": 3, "isLiked": true, "isOwner": true,
    "nsfwFlagged": false, "nsfwRate": 0.1, "username": "…"
  }],
  "page": 1, "limit": 20, "count": 20,
  "nextBeforeDate": "…"
}

A row rendered on a next channel carries videoModel / imageModel: "next" and aiModel: "gen8.0".

count is the rows in this page, not the collection total. nextBeforeDate is present only while a further page may exist and the rows are in newest-first date order (the default sort, no relevance-ranked search) — feed it back as beforeDate; for any other ordering, page with page. prompt, nsfwRate and folderId are owner-only; likes is the total count and isLiked is whether your account liked the row. source is web (studio), sdk, mcp or api.

The cross-user public feed, newest-published first. Query: limit (1..48, default 24) · page (1-based, ≤ 1000) · includeNsfw (1 to include flagged rows).

{ "creations": [ … ], "page": 1, "limit": 24, "hasMore": true }

Rows are the same shape as above; rows you don't own hide their prompts.

Returns { "creation": { … } } — the full owner view: prompts, dimensions, references, NSFW rating, lineage, folder, timestamps, plus downloadUrl. Note the key is creation.id here, not creationId. 404 CREATION_NOT_FOUND when unknown, not yours, or deleted.

Permanent delete requires the creation to be in trash first, else 409 NOT_IN_TRASH. Other codes: 404 CREATION_NOT_FOUND, 403 NOT_AUTHORIZED, 410 ALREADY_DELETED, 403 INVALID_FOLDER.

Clone makes a byte-identical duplicate (images only) with its own CDN file, inheriting the original's description/tags/moderation verdict; no credit cost, but the upload tier + storage-quota gates apply. Clone-specific codes: 403 CLONE_FORBIDDEN, 400 CLONE_UNSUPPORTED_MEDIA (video/gif), 409 CREATION_HAS_NO_MEDIA, 403 UPLOAD_NOT_ALLOWED_FOR_TIER, 413 STORAGE_QUOTA_EXCEEDED.

like is an idempotent SET, not a toggle — retries are safe, and changed: false means the state already matched. Any live creation is likeable; trashed/deleted rows answer 410. reorder stamps creationIds[i] with sort index i (ids you don't own are silently skipped). batch is owner-only; rows whose state doesn't fit the action are counted in skipped — delete requires rows already in trash.

All four are owner-only. flag-nsfw is a manual safe → NSFW escalation (the reverse direction isn't exposed here) and flips the CDN gate immediately. The other three are cached on the row: the first call burns a vision-LLM pass (hence the generate scope), repeats answer from the stored result with cached: true. Codes: 400 NOT_FLAGGED (explain on a clean row), 422 SCORE_PARSE_FAILED, 503 = the LLM pass didn't land — retry later.

409 CREATION_IN_TRASH — restore it first. 409 UPLOADED_NOT_PUBLISHABLE — uploaded source files can't be published, only your own generations.

multipart/form-data with a single file field named file, plus optional text fields:

curl -X POST https://dapp.2dai.io:444/v1/uploads \
  -H "Authorization: Bearer $TWODAI_API_KEY" \
  -F "file=@./ref.jpg" \
  -F "targetFolderId=$FOLDER_ID"

Accepted types: JPEG, PNG, WebP, GIF, MP4 (video uploads are tier-gated), and MP3 — the audio reference of a Gen8 Preview video clip: 5 minutes max, Holder tier and up, no vision caption (the file name and length label it); the row comes back with mediaKind: "audio" and duration in seconds. Per-account size cap applies (10 MB on the base tier).

Returns the created creation object directly (not wrapped).

Notable errors: 400 NO_FILE, 400 INVALID_MIME, 403 UPLOAD_NOT_ALLOWED_FOR_TIER, 403 VIDEOS_NOT_ALLOWED, 403 AUDIO_NOT_ALLOWED, 400 AUDIO_TOO_LONG { maxSeconds }, 403 NSFW_REJECTED, 403 INVALID_FOLDER, 413 FILE_TOO_LARGE, 413 STORAGE_QUOTA_EXCEEDED, 409 DUPLICATE_IN_FOLDER (identical bytes already in that folder), 429 UPLOAD_IN_PROGRESS.

Advisory pre-flight dedup: does a creation with this content hash already exist? Query: md5 (32 hex chars — the md5 of the file bytes) · folderId (optional; omit to check the drive root).

{ "duplicate": true, "existingCreationId": "…", "folderId": "…" }

Saves the full upload round-trip, but the upload itself still re-checks — a concurrent upload can race a false, so treat it as a hint, not a lock.

An account holds up to 500 folders — 409 FOLDER_LIMIT_REACHED past the cap. Folder shape:

{ "folderId": "…", "title": "…", "description": "…", "icon": "…",
  "kind": "private", "isPublicShared": false, "isShared": false,
  "posterCreationId": "…", "groupId": "…", "isFavorite": false,
  "createdAt": "…", "updatedAt": "…" }

groupId is absent when the folder is ungrouped; isFavorite marks the sidebar star (starred folders feed the smart=favorites lens).

The list is newest-first by createdAt by default, and nextBeforeDate is present only when a further page may exist — feed it back as beforeDate, same as GET /v1/creations.

sort accepts the same vocabulary as the dashboard: index, date-desc, date-asc, name-asc, name-desc, update-desc. Note the interaction with the cursor: beforeDate filters on the creation date, so it can only page a date-descending sequence without skipping or repeating rows. Ask for name-asc (or any non-date order) and you get your ordering, but nextBeforeDate is omitted — raise limit instead, which at 100 covers any realistic number of collections. The alternative, accepting sort and handing back a cursor that silently corrupts the sequence, would be the worse contract.

Errors: 400 INVALID_TITLE (with maxLength), 400 NO_UPDATES, 400 FIXED_KIND_PROTECTED (system folders can't be renamed or deleted), 404 NOT_FOUND, 403 NOT_AUTHORIZED.

Groups are the collapsible sections the studio's cloud-drive sidebar organises collections into. They hold folders, never creations directly:

Group shape: { groupId, title, sortIndex, collapsed, createdAt, updatedAt }. An account holds up to 100 groups (409 GROUP_LIMIT_REACHED). Deleting a group only detaches its member folders back to the ungrouped pane — folders and creations are never deleted through this route. Move folders in and out via PATCH /v1/folders/:id with groupId.

Read-only account analytics, all scope read. overview and top are served from a server-side cache; their cache block ({ computedAt, ageSeconds, stale }) says how fresh the numbers are — stale: true means a background refresh was kicked, re-fetch shortly.

{
  "storage": { "usedBytes": 0, "quotaBytes": 0, "imageBytes": 0,
               "videoBytes": 0, "uploadBytes": 0, "trashBytes": 0 },
  "counters": { "totalCreations": 0, "weekCreations": 0, "weekDelta": 0,
                "privateFolders": 0, "sharedFolders": 0,
                "favoriteFolders": 0, "trashCreations": 0 },
  "streak": { "days": 0 },
  "smartSummaries": [{ "id": "faces", "count": 0 }],
  "toolsRecent": { "image-gen": { "total": 0, "recentIds": ["…"] } },
  "cache": { "computedAt": "…", "ageSeconds": 12, "stale": false }
}

Generation volume + spend over the window (any other days is a 400); a live aggregate memoized ~60 s per window:

{
  "days": 30,
  "totals": { "count": 0, "costUsd": 0 },
  "byDay": [{ "day": "2026-08-01", "count": 0, "costUsd": 0 }],
  "byTool": [{ "toolKind": "image-gen", "count": 0, "costUsd": 0 }],
  "bySource": { "machine": { "count": 0, "costUsd": 0 },
                "studio":  { "count": 0, "costUsd": 0 } }
}

machine is work made through keys (SDK / MCP / raw REST); studio is the web app.

Most-used references (with the config the studio would suggest for each), styles and keywords:

{
  "topRefs": [{ "referenceCreationId": "…", "useCount": 0,
                "suggestedTool": "character-ref", "latestUsedAt": "…",
                "suggestedConfig": { "quality": "high", "style": null,
                                     "motionStyle": null, "requestedDuration": null,
                                     "isEnhanced": false, "frameInterpolation": false } }],
  "topStyles": [{ "style": "…", "count": 0 }],
  "topKeywords": [{ "tag": "…", "count": 0 }],
  "cache": { "computedAt": "…", "ageSeconds": 12, "stale": false }
}

The money family is read-only by construction: no deposit, withdraw, swap or lock operation exists anywhere on the API-key surface — those live in the dashboard. The wallet reads require the opt-in finance scope (never in the mint defaults); the two catalogue reads only need read.

amount is a magnitude — the direction comes from type. secondaryUsd is set on swap rows only. A key without the scope gets 403 { "error": "MISSING_SCOPE", "requiredScope": "finance", "scopes": [ … ] }.

Send the same bearer; the response is the raw bytes (not JSON), with content-type, content-length and etag passed through.

curl -L "https://dapp.2dai.io:444/cdn/file/<outputCdnId>" \
  -H "Authorization: Bearer $TWODAI_API_KEY" -o out.jpg

You can append an extension (/cdn/file/<id>.jpg) and pass CDN transform params: ?s=<px> scales the longest edge keeping the aspect ratio (what you want for previews), ?w=<px> / ?h=<px> target one axis and may crop. ?s takes precedence over ?w / ?h when both are sent.

curl -L "https://dapp.2dai.io:444/cdn/file/<id>?s=512" \
  -H "Authorization: Bearer $TWODAI_API_KEY" -o preview.jpg

Publicly-shared creations serve without auth; everything else requires the key that owns them. 404 for unknown ids, 403 when the key may not see that file.

• Pending generations are capped per tier (4 on the base tier) — 409 QUEUE_LIMIT_REACHED when you exceed it. Poll and retry.
• Pagination — limit maxes out at 100 (48 on the feed; 50 on wallet transactions).
• References are capped per tool (strict 400 TOO_MANY_REFS — see the caps table above).
• Bulk — reorder and batch take at most 1000 ids per call.
• Drive — 500 folders and 100 folder groups per account (409 FOLDER_LIMIT_REACHED / GROUP_LIMIT_REACHED).
• JSON bodies are capped at 5 MB; prompts at the account's promptMaxChars (GET /v1/me; tier ladder 1,500 → 20,000).
• Idempotency — submits carry a clientToken. Re-sending an identical call within a few seconds returns 409 IDEMPOTENT_RETRY instead of charging twice. Pass your own token to control the window. Without a valid token the server derives one from the call itself (prompt, settings, source and reference ids, audio reference, 5 s bucket), so two submits that differ by a reference are never mistaken for a retry.
• Rate/abuse — repeated auth failures and 404s count against your IP; a blocked IP gets 429 with an empty body on every route.