API Reference

This section provides a detailed reference for all available endpoints and parameters.

Base URL

Base URL: https://api.frame3d.dev

Model Input

The model parameter is required for all rendering endpoints and can be provided in two formats:

1. URL

A publicly accessible URL to a .glb file.

{ "model": "https://example.com/model.glb" }

2. Base64 Data URL

A base64-encoded string of the .glb file.

{ "model": "data:model/gltf-binary;base64,Z2xURg..." }

Error Responses

If a request fails, the API returns a standardized error response:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable error message.",
    "details": "Optional technical details."
  }
}

Error Code	Description
`MISSING_API_KEY`	No API key was provided in the request headers.
`INVALID_API_KEY`	The provided API key is invalid or revoked.
`INSUFFICIENT_BALANCE`	Your account does not have enough credits.
`RATE_LIMITED`	You have exceeded the rate limit (default 100/min).
`GATEWAY_ERROR`	An error occurred in the API gateway.
`INVALID_MODEL`	The provided GLB file is corrupted or invalid.
`DOWNLOAD_FAILED`	The API could not download the model from the URL.
`RENDER_FAILED`	An unexpected error occurred during rendering.
`INVALID_PARAMS`	The request body contains invalid parameters.
`TIMEOUT`	The rendering process exceeded the time limit.
`INTERNAL_ERROR`	A generic server-side error occurred.

Metadata Object

When includeMetadata is set to true in any endpoint, the response will contain a metadata object with the following fields, extracted using @gltf-transform/core.

Field	Type	Description
`triangles`	number	The total number of triangles in the model.
`vertices`	number	The total number of vertices in the model.
`meshes`	number	The number of unique mesh objects.
`materials`	string[]	An array of material names found in the model.
`textures`	number	The number of textures in the model.
`fileSize`	number	The original file size of the GLB model in bytes.
`isTextured`	boolean	`true` if any material in the model uses a texture.
`animations`	array	An array of animation objects in the model.

Animation Object

Each animation object in the animations array contains:

Field	Type	Description
`name`	string	The name of the animation (or "Unnamed").
`duration`	number	The duration of the animation in seconds.
`channels`	number	The number of animation channels in this clip.

Limitations

POST /single