API Documentation

API reference

Every public endpoint of the Generate API on one page — request parameters, defaults, and response shapes. Worked examples live on the topic pages; this is the cheat sheet.

Conventions

Base URL: https://api.everythingstudios.ai
Format: JSON in, JSON out. All ids are ULIDs; all timestamps are ISO 8601 UTC.
Auth: every endpoint requires an API key esk_…, sent as Authorization: Bearer esk_… (recommended) or x-api-key: esk_…. See Authentication.
Errors: {"error":{"code","message"}} envelope — match on code. Full table on Errors & limits. Exception: auth failures return 403 with the gateway body {"message":"Forbidden"}.

Task object

The shared response shape returned by GET /v1/jobs/{id}, each item in GET /v1/jobs, and mirrored in task.updated webhook payloads.

Field	Type	Required	Description
task_id	string	always	ULID; the same value as the `job_id` returned at creation.
type	string	always	Always `image-to-3d` — the only supported job type.
status	string	always	`PENDING` \| `QUEUED` \| `IN_PROGRESS` \| `SUCCEEDED` \| `FAILED` \| `CANCELED`.
progress	number	always	0–100, advisory; `status` is the source of truth.
model_urls	object \| null	no	Contains the key `glb` — a permanent CDN URL; GLB is the only format produced today.
thumbnail_url	string \| null	no	Permanent JPEG thumbnail on the same CDN.
error	object \| null	no	`{ code, message }` on `FAILED` jobs; `null` otherwise.
created_at	string	always	ISO 8601 creation timestamp.
finished_at	string \| null	always	ISO 8601; `null` until the job reaches a terminal status.

Endpoints

POST/v1/jobs

Submit an asynchronous generation job. Returns 202 with the job id immediately.

Top-level request body:

Field	Type	Required	Description
type	string	yes	Must be `image-to-3d` — the only supported job type. Other values are accepted but reserved for upcoming features and currently fail during processing.
input	object	yes	The job input — see the input table below.
options	object	optional	Accepted for forward compatibility; not yet applied. Default: unset.
idempotency_key	string	optional	1–256 chars; resubmitting the same key returns the original job instead of creating a duplicate. Scoped to your account. Default: none.

input

Field	Type	Required	Description
image_urls	string[]	yes	Exactly 1 image URL — an `http(s)` URL (https recommended; fetched server-side, max 25 MiB) or an inline `data:image/(png\|jpeg\|webp);base64,…` URI (decoded max 4 MiB).

options is accepted for forward compatibility; its fields are not yet applied, and GLB is the only output format produced today.

202 Accepted

{
  "job_id": "01JAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}

400 invalid_request, 402 insufficient_balance — see Errors & limits.

GET/v1/jobs/{id}

Retrieve a single job by the id returned at creation. No request body.

200 OK

{
  "task_id": "01JAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "type": "image-to-3d",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_urls": {
    "glb": "https://assets.everythingstudios.ai/models/01JAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/model.glb"
  },
  "thumbnail_url": "https://assets.everythingstudios.ai/models/01JAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/thumb.jpg",
  "error": null,
  "created_at": "2026-01-15T10:04:11Z",
  "finished_at": "2026-01-15T10:07:52Z"
}

Field-by-field detail on the Job status page.

GET/v1/jobs

Page through your account's jobs, newest first, cursor pagination.

Query parameters:

Field	Type	Required	Description
status	string	optional	Filter by one of the six statuses; any other value returns `400`. Default: none (all statuses).
limit	number	optional	Page size, 1–100. Default: 20.
cursor	string	optional	Opaque token from a previous response's `next_cursor`; an invalid token returns `400 invalid_cursor`. Default: first page.

200 OK

{
  "jobs": [
    {
      "task_id": "01JAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "type": "image-to-3d",
      "status": "SUCCEEDED",
      "progress": 100,
      "model_urls": {
        "glb": "https://assets.everythingstudios.ai/models/01JAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/model.glb"
      },
      "thumbnail_url": "https://assets.everythingstudios.ai/models/01JAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/thumb.jpg",
      "error": null,
      "created_at": "2026-01-15T10:04:11Z",
      "finished_at": "2026-01-15T10:07:52Z"
    },
    {
      "task_id": "01JBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
      "type": "image-to-3d",
      "status": "SUCCEEDED",
      "progress": 100,
      "model_urls": {
        "glb": "https://assets.everythingstudios.ai/models/01JBBBBBBBBBBBBBBBBBBBBBBBBBBBBB/model.glb"
      },
      "thumbnail_url": "https://assets.everythingstudios.ai/models/01JBBBBBBBBBBBBBBBBBBBBBBBBBBBBB/thumb.jpg",
      "error": null,
      "created_at": "2026-01-14T18:22:03Z",
      "finished_at": "2026-01-14T18:26:41Z"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0xNFQxODoyMjozM1oifQ"
}

next_cursor is omitted on the last page.

GET/v1/balance

Your current prepay balance, the minimum balance required to start new jobs, and the per-second rates you are charged. No request body.

200 OK

{
  "balance_usd": 24.18,
  "min_balance_usd": 1.0,
  "rates": {
    "g5": 0.000844,
    "g6e": 0.001556,
    "g7e": 0.002333
  }
}

Rates are USD per second of inference keyed by serving instance; the platform picks the instance per job — read the price from rates, don't hardcode. Details on the Balance & billing page.

PUT/v1/webhook-endpoint

Field	Type	Required	Description
url	string	yes	The https URL event deliveries are sent to; non-https or missing returns `400 invalid_request`.

First-time configuration returns {"url":"…","secret":"…"}; later URL-changing PUTs return {"url":"…"} without the secret. The current secret is always retrievable via GET /v1/webhook-endpoint.

200 OK

{
  "url": "https://your-app.example.com/webhooks",
  "secret": "whsec_…"
}

GET/v1/webhook-endpoint

Retrieve your configured webhook endpoint. No request body.

Returns {"url":"…","secret":"…"}; never configured returns 404 not_configured.

200 OK

{
  "url": "https://your-app.example.com/webhooks",
  "secret": "whsec_…"
}

DELETE/v1/webhook-endpoint

Remove your webhook endpoint; deliveries stop immediately. No request body.

Returns 204 with an empty body.

POST/v1/webhook-endpoint/rotate

Generate a new signing secret. The old secret stops working immediately. No request body.

Returns {"secret":"…"} with the new secret; the old secret stops working immediately. No endpoint configured returns 404 not_configured.

200 OK

{
  "secret": "whsec_new…"
}

POST/v1/webhook-endpoint/test

Queue a signed ping event to verify your integration. No request body.

Returns 202 {"queued":true}; a signed ping event arrives roughly 10 seconds later; no endpoint configured returns 409 not_configured.

Delivery semantics, HMAC signature verification (x-generate-timestamp + x-generate-signature), and the task.updated/ping event schemas are on the Webhooks page.