API Docs

Creation accounts and provider-funded usage

Authentication and billing

These website endpoints require a signed-in website session. Mutations also require the session CSRF token (X-CSRF-Token). They do not accept the public app API key as a substitute. Accounts can open Forge and connect providers without an app subscription. Every model/file endpoint still checks ownership. A website login and a provider API account are separate.

ChatGPT subscription billing does not fund general API requests. Codex's ChatGPT sign-in is not a general third-party image API login. Do not submit ChatGPT cookies, passwords, or Codex access tokens as provider keys. See OpenAI billing documentation.

Own-key Forge and supported Asset Studio image generations use 0 app tokens, with charges applied to the selected provider account. App-funded generations retain the app's priced model shortlist and token/subscription requirements. Connecting or refreshing a key reads the provider's model directory, not a paid generation. Image-to-3D GPU compute and format conversion are separate from provider API billing.

Provider connections

Supported provider path values: openai, anthropic, gemini, openrouter.

OpenRouter sign-in (OAuth PKCE)

| Method | Path | Notes |

|---|---|---|

| GET | /forge/providers/openrouter/connect | Signed-in website session. Sets a 10-minute HttpOnly cookie holding state and the PKCE verifier, then redirects to https://openrouter.ai/auth with an S256 challenge. Guests are redirected to login first. |

| GET | /forge/providers/openrouter/callback?code=...&state=... | Checks state, exchanges the code at https://openrouter.ai/api/v1/auth/keys, validates the key once, stores it encrypted as the openrouter connection, then redirects to /forge?settings=providers&openrouter=connected. Failures redirect with openrouter=failed or openrouter=expired. |

OpenRouter validation reads GET https://openrouter.ai/api/v1/key and GET https://openrouter.ai/api/v1/models in parallel. Its returned text-input/text-output models are offered in Forge, including models outside the app's priced shortlist. Image-output models with text input are offered in Asset Studio; reference-image generation additionally requires image input. openrouter/auto is offered only when returned by the directory, never injected as a fallback. Usage is billed to the user's OpenRouter account.

API key endpoints

| Method | Endpoint | Request | Response |

|---|---|---|---|

| GET | /api/forge/provider-connections | None | { "ok": true, "providers": [...] } |

| PUT | /api/forge/provider-connections/:provider | JSON { "credential": "provider-api-key" }, nonempty, at most 5000 characters | { "ok": true, "connection": { "id", "provider", "keyPreview", "validationStatus", "validatedAt", "providerAccountMetadata", "createdAt", "updatedAt" } } |

| POST | /api/forge/provider-connections/:provider/test | JSON { "connectionId": 7 }, optional owned connection ID | Same safe connection response |

| DELETE | /api/forge/provider-connections/:provider | None | { "ok": true, "disconnected": true, "provider": "gemini" } |

Credentials are validated once before storage, encrypted on the server, and never returned. Failed replacement leaves the previous connection unchanged. Connections are user-owned, not shared across project members. GET provider state includes provider setup links/instructions, app availability, and safe connection metadata. POST /:provider/test explicitly refreshes the stored model catalog. Existing connections must be refreshed once to populate their catalogs; reload Forge or Studio afterward.

providerAccountMetadata contains:

  • catalogVersion: 1.
  • models: compatible Forge text models with id (provider:model), provider, providerLabel, model, label, modelLabel, supportsImageInput, supportsStreaming, supportsStructuredOutput, maxOutputTokens, contextLength, supportedParameters, inputPer1M, outputPer1M, applicationTokenCost: null, and userOnly: true.
  • imageModels: supported image generation models with id, provider, model, label, modelLabel, supportsImageInput, outputModalities, tokenCost: 0, and requiresUserCredential: true.
  • availableModels: Forge text model IDs without the provider prefix.
  • modelCount, imageModelCount, listedModelCount: compatible text, compatible image, and total directory entry counts.

Unknown token limits or prices are null, not free. OpenRouter supplies declared modalities, supported parameters and prices. Gemini supplies generation methods and token limits. OpenAI's directory does not supply capabilities/prices, so supported text/image families are classified by model ID. Anthropic and Gemini pagination is followed. Audio, embeddings, realtime, specialized computer-use tools and other incompatible operations are not Forge code models. Directory inclusion does not guarantee provider entitlement, quota, availability or useful geometry.

Example request (illustrative session and CSRF placeholders, never put keys into URLs):

curl -X PUT 'https://crateyard.com/api/forge/provider-connections/openai' \
  -H 'Cookie: {{sessionCookie}}' -H 'X-CSRF-Token: {{csrfToken}}' \
  -H 'Content-Type: application/json' \
  -d '{"credential":"example-provider-api-key"}'

Example response:

{"ok":true,"connection":{"id":7,"provider":"openai","keyPreview":"example...key","validationStatus":"valid","validatedAt":"2026-09-01T00:00:00.000Z","providerAccountMetadata":{"catalogVersion":1,"models":[{"id":"openai:gpt-4.1","provider":"openai","model":"gpt-4.1","label":"gpt-4.1","supportsImageInput":true,"inputPer1M":null,"outputPer1M":null}],"imageModels":[{"id":"openai:gpt-image-1","provider":"openai","model":"gpt-image-1","label":"gpt-image-1","supportsImageInput":true,"tokenCost":0,"requiresUserCredential":true}],"availableModels":["gpt-4.1"],"modelCount":1,"imageModelCount":1,"listedModelCount":2},"createdAt":"2026-09-01T00:00:00.000Z","updatedAt":"2026-09-01T00:00:00.000Z"}}

Forge chat payment source

POST /api/forge/chats, JSON body:

  • tool: ll3m or managed_blender, defaults to ll3m.
  • providerOptionId: an available provider:model identifier from the Forge model picker.
  • credentialSource: application (default) or user_provider.
  • connectionId: owned provider connection ID for own-key usage.

Response: { "ok": true, "chat": { "id", "publicId", "title", "tool", "defaultProvider", "defaultModel", "credentialSource", "providerConnectionId", ... } }.

Example request body:

{"tool":"ll3m","providerOptionId":"gemini:gemini-2.5-pro","credentialSource":"user_provider","connectionId":7}

Example response excerpt:

{"ok":true,"chat":{"id":11,"publicId":"example-chat","credentialSource":"user_provider","providerConnectionId":7}}

Use a currently available model identifier, not necessarily the illustrative model above. Own-key selections must match that user's stored provider catalog exactly; they do not need to appear in the app's priced shortlist. Forge exposes a provider filter and model search. Text-only models reject reference images. OpenAI uses Chat Completions, Responses, or legacy Completions according to model family, including listed fine-tuned text models; provider-specific unsupported parameters are omitted. Generations retain the pinned model and payment source. A disconnected key or removed model fails explicitly, never switching to another model or app funding.

Legacy o1-mini/o1-preview use non-streaming Chat Completions; o1-pro uses a single non-streaming Responses request. Other Responses models stream where supported. Failed or incomplete outputs, including partial provider streams, are not accepted as completed geometry.

Asset Studio image payment source

Website form endpoints:

  • POST /asset-creator/create/3d-preview: text-to-image.
  • POST /asset-creator/create/image-to-3d-preview: reference-image generation.
  • POST /asset-creator/task/:taskId/regenerate: new image/model version.

For JSON responses send Accept: application/json or X-Requested-With: XMLHttpRequest. Successful initial generation returns HTTP 201 { "taskId": 123 }; regeneration returns HTTP 200 { "taskId": 124 }. Browser form submissions redirect to the new task.

Image request fields (urlencoded or multipart):

| Field | Meaning |

|---|---|

| project_asset_id, project_id | Target project asset/project, access is checked |

| prompt | Required for text generation, optional for reference generation. Studio text areas allow 2000 characters |

| pipeline | App pipeline ID such as nano_banana, or an exact owned image catalog ID such as openai:gpt-image-1 or openrouter:vendor/image-model. Required for initial own-key generation |

| credential_source | application (default) or user_provider |

| image | Image upload for reference generation, alternatively use_existing_file_id for an accessible stored image |

| angle_mode, style, t_pose, optimize_for_rigging | Existing image preparation options |

Own-key images require a validated OpenAI, OpenRouter or Gemini connection and an exact model from its stored imageModels catalog. OpenAI GPT Image supports text and reference generation; DALL-E choices are text-only. OpenRouter models use their declared text/image input and image output capabilities. Gemini image models support reference generation; Imagen choices are text-only. Incompatible models are excluded from the reference picker and rejected on the server.

Own-key images use 0 app tokens, without an app subscription. The selected provider bills generation. Each task makes one image generation request; multi-angle output is split locally when possible. Automatic title/description generation is disabled for own-key tasks, so a separate model or app key is not invoked. Image-to-3D GPU compute remains app-funded. Existing app-funded image pipelines, including Gemini's subscription requirements, are unchanged.

Example:

curl -X POST 'https://crateyard.com/asset-creator/create/3d-preview' \
  -H 'Cookie: {{sessionCookie}}' -H 'X-CSRF-Token: {{csrfToken}}' \
  -H 'Accept: application/json' \
  --data-urlencode 'prompt=Stylized wooden chest, separate lid, plain background' \
  --data 'project_id=1&project_asset_id=2&pipeline=openai%3Agpt-image-1&credential_source=user_provider'

Response:

{"taskId":123}

Task settings persist payment source, provider, exact provider_model, owned connection ID, and connection revision, never the key. Workers decrypt at execution, validate the pinned catalog model again, use only that connection, and do not switch to app funding, another image model, or a fallback request configuration on failure. Replaced/disconnected connections or removed models stop queued work. Refreshing a connection also updates its revision, so queued image work from before that refresh stops. Interrupted user-funded work is marked failed, not automatically resubmitted. Provider usage already consumed may still be billed.

Image regeneration defaults to the original payment source unless credential_source explicitly selects another. The Studio dialogs show the chosen source before submission. Canceled or failed zero-app-token tasks never receive an app-token refund or debit on requeue. Provider charges cannot be refunded by the app.

The task page's Generate Again dialog retains the original funding source and exact model. Own-key choices show 0 app tokens and include compatible image models from connected providers. Studio's Generate Again restoration also retains the prior model. An unavailable prior model is shown explicitly and blocks submission until another available model is chosen or the account is refreshed. To change funding, use an Asset Studio image dialog. Regeneration preserves the selected app-funded provider/model too; unavailable connections fail rather than charging app tokens.

Errors and rate limits

  • 401: unauthenticated JSON request; website routes may redirect to login.
  • 403: invalid CSRF, project access, or missing app subscription for app-funded Gemini images.
  • 404: unsupported provider, unavailable task/model, or connection not owned by the session user.
  • 400: malformed body, missing prompt, or invalid task ID.
  • 402: insufficient app tokens for app-funded execution.
  • 422: invalid key, incompatible or unlisted own-key model, missing/unvalidated connection, missing own-key model selection, or invalid form selection. Refresh the catalog explicitly when it is stale.
  • 503: provider validation timeout, unavailable service, or rate limit. Generation-time provider errors fail the task rather than switching funding.

These session endpoints have no endpoint-specific numeric per-minute rate limit configured. Provider account quotas and model rate limits apply. Each explicit submission is one task attempt; no own-key retry or automatic resubmission is added.

Unified editor handoff

GET /tools/mesh-editor?forgeGenerationId=123 loads a finished, user-owned Forge generation through its authenticated model endpoint. Guests go to login with the full destination preserved. Unavailable/foreign Forge models return a 404 page, not another user's model. Asset Studio keeps its existing taskId, project_asset_id, project_id, and texture-version handoff.

Exporting a VRChat Unity package is not an upload or a compatibility guarantee. Import with Creator Companion and validate in the supported Unity SDK before upload. Stock Unity needs a glTF importer for GLB; use FBX for ordinary Unity import.

The public workflow pages explain which creation method to use: /use-case/vrchat and /instructions/vrchat-avatar cover starting inputs, cleanup before rigging, PC versus Quest budgets, the package setup menu, Creator Companion, SDK validation and upload blockers. /use-case/concept-art covers reference preparation and image-to-model choices. /use-case/3d-printing covers watertightness, physical scale, supported exports and slicer preparation, without promising native STL export or automatic print repair. /use-case/game-development covers engine import, and /use-case/indie-dev covers low-poly resources, machines and upgrade tiers. Forge is the prop workflow; Asset Studio is the textured-character workflow. Generation is not a guarantee of topology, performance rank or engine compatibility; inspect and validate the exported asset.