# Detail & Texture
Source: https://docs.thrixel.com/docs/detail

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

Phase 4 takes a completed submission (the "control mesh") and produces a high-resolution
textured model using a GPU pipeline. You can also remesh or retexture an existing Phase 4
result without regenerating from scratch.

---

## Detail and texture a model

<Callout title="POST /api/v1/detailer/submit">
  Requires API key.
</Callout>

Generate a high-resolution textured mesh from a parent submission. A reference image and
prompt guide the texture style; if omitted, they are auto-generated from the parent.

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `parent_submission_id` | string (required) | ID of the submission to detail. |
| `image` | string | Reference image (base64 or HTTPS URL). Auto-generated if omitted. |
| `mesh` | string | Override control mesh (base64 or URL). Defaults to the parent's GLB. |
| `prompt` | string | Text description of the desired appearance. |
| `seed` | integer | Random seed for reproducibility. 0–999,999. Default: `42`. |
| `texture_size` | integer | Output texture resolution. Values: `512`, `768`, `1024`, `2048`. Default: `768`. |
| `control_mesh_voxelize_res` | integer | Voxel resolution for mesh conditioning. 256–2048. Default: `512`. |
| `decimation_target` | integer | Target triangle count after decimation. 10,000–500,000. Default: `160000`. |
| `pipeline_type` | string | Detailer pipeline variant. Values: `1024_cascade`, `1536_cascade`. |
| `control_mesh_ss_lat_noise_t0idx` | integer | Sparse-structure noise timestep. 0–12. |
| `preserve_parts` | boolean | Keep separate mesh parts intact during decimation. Default: `true`. |
| `focus_on_node_names` | string[] | Node names to focus the generation on. Empty = whole mesh. |
| `focus_mode` | string | Where to apply focus during generation. Values: `latent`, `sparse_structure`. Default: `latent`. |
| `project_id` | string | Assign to a project. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/detailer/submit \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_submission_id": "a1b2c3d4-...",
    "prompt": "weathered bronze, green patina",
    "texture_size": 1024
  }'
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "submission_id": "e5f6a7b8-...",
  "status": "queued",
  "created_at": "2026-04-20T14:45:30Z",
  "reference_image_url": "https://api.thrixel.com/api/v1/detailer/reference/e5f6a7b8-..."
}
```

---

## Re-decimate a Phase 4 mesh

<Callout title="POST /api/v1/detailer/remesh">
  Requires API key.
</Callout>

Produce a new triangle count from an existing Phase 4 checkpoint without regenerating
texture. Fast — reuses stored latents.

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `parent_submission_id` | string (required) | ID of a completed Phase 4 submission. |
| `decimation_target` | integer | Target triangle count. 10,000–500,000. Default: `200000`. |
| `remesh` | boolean | Run quad remeshing before decimation. Default: `true`. |
| `project_id` | string | Assign to a project. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/detailer/remesh \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_submission_id": "e5f6a7b8-...",
    "decimation_target": 80000
  }'
```

  </Tab>
</Tabs>

---

## Re-texture an existing mesh

<Callout title="POST /api/v1/detailer/retexture">
  Requires API key.
</Callout>

Regenerate textures for a completed Phase 4 submission. Three modes: rebake (re-project
existing), regenerate (new texture from image), or rebake_texture (UV rebake only).

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `parent_submission_id` | string (required) | ID of a completed Phase 4 submission. |
| `texture_size` | integer | Output texture resolution. Values: `512`, `768`, `1024`, `2048`. Default: `1024`. |
| `mode` | string | Retexture strategy. Values: `rebake`, `regenerate`, `rebake_texture`. Default: `rebake`. |
| `image` | string | Reference image for `regenerate` mode. |
| `apply_to_node_names` | string[] | Restrict retexture to specific mesh nodes. |
| `project_id` | string | Assign to a project. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/detailer/retexture \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_submission_id": "e5f6a7b8-...",
    "mode": "rebake",
    "texture_size": 2048
  }'
```

  </Tab>
</Tabs>

---

## Fetch reference image

<Callout title="GET /api/v1/detailer/reference/{submission_id}">
  Public.
</Callout>

Returns the user-provided or auto-generated reference image used to guide the Phase 4
pipeline. PNG.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of a Phase 4 submission. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -L -o reference.png \
  https://api.thrixel.com/api/v1/detailer/reference/e5f6a7b8-...
```

  </Tab>
</Tabs>


---

# Download & Export
Source: https://docs.thrixel.com/docs/download

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

GLB is produced when a submission completes. Other formats are converted on-demand:
either inline via the unified `/download` endpoint (which waits for the result), or
asynchronously via the `/convert` job API.

---

## Download a submission asset

<Callout title="GET /api/v1/{submission_id}/download">
  Public.
</Callout>

Unified endpoint for all downloadable artifacts. GLB is always ready; FBX/OBJ/STL/USDZ
trigger an on-demand conversion if not yet cached.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission. |

### Query Parameters

| Name | Type | Description |
| --- | --- | --- |
| `format` | string | Asset format. Values: `glb`, `fbx`, `obj`, `stl`, `usdz`, `py`, `thumbnail`, `reference_image`. Default: `glb`. |
| `index` | integer | Index for `reference_image` format (0–5). Default: `0`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
# GLB (instant)
curl -L -o model.glb \
  "https://api.thrixel.com/api/v1/a1b2c3d4-.../download?format=glb"

# FBX (triggers conversion, may take a few seconds)
curl -L -o model.fbx \
  "https://api.thrixel.com/api/v1/a1b2c3d4-.../download?format=fbx"
```

  </Tab>
</Tabs>

---

## Queue a conversion job

<Callout title="POST /api/v1/convert">
  Public.
</Callout>

Async alternative to `/download` for non-GLB formats. Returns immediately with a `job_id`
to poll. Re-requesting the same (submission, format) returns the existing ready job
unless `force=true`.

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission to convert. |
| `format` | string (required) | Target format. Values: `fbx`, `obj`, `stl`, `usdz`. |
| `force` | boolean | Re-run the conversion even if a ready job exists. Default: `false`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"submission_id": "a1b2c3d4-...", "format": "usdz"}'
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "job_id": "f7a8b9c0-...",
  "submission_id": "a1b2c3d4-...",
  "format": "usdz",
  "status": "queued",
  "error": null,
  "download_url": null,
  "status_url": "https://api.thrixel.com/api/v1/convert/f7a8b9c0-..."
}
```

---

## Check conversion status

<Callout title="GET /api/v1/convert/{job_id}">
  Public.
</Callout>

Returns the current status of a conversion job. Poll until status becomes `ready` or
`failed`.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `job_id` | string (required) | UUID returned by `POST /convert`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl https://api.thrixel.com/api/v1/convert/f7a8b9c0-...
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "job_id": "f7a8b9c0-...",
  "submission_id": "a1b2c3d4-...",
  "format": "usdz",
  "status": "ready",
  "error": null,
  "download_url": "https://api.thrixel.com/api/v1/convert/f7a8b9c0-.../download",
  "status_url": "https://api.thrixel.com/api/v1/convert/f7a8b9c0-..."
}
```

---

## Download a converted file

<Callout title="GET /api/v1/convert/{job_id}/download">
  Public.
</Callout>

Returns the converted file once ready. 409 if still queued/running, 410 if the job
failed.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `job_id` | string (required) | UUID of a ready conversion job. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -L -o model.usdz \
  https://api.thrixel.com/api/v1/convert/f7a8b9c0-.../download
```

  </Tab>
</Tabs>


---

# Gallery
Source: https://docs.thrixel.com/docs/gallery

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

Published models curated by the Thrixel team. All endpoints are public.

---

## List gallery items

<Callout title="GET /api/v1/gallery">
  Public.
</Callout>

Returns a flat list of published gallery items. Each item includes a `parent_id` so
you can reconstruct the hierarchy on the client.

### Query Parameters

| Name | Type | Description |
| --- | --- | --- |
| `limit` | integer | Max items. Default: `500`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl "https://api.thrixel.com/api/v1/gallery?limit=100"
```

  </Tab>
</Tabs>

---

## Get gallery item

<Callout title="GET /api/v1/gallery/{item_id}">
  Public.
</Callout>

Returns a single gallery item plus its direct children.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `item_id` | string (required) | UUID of the gallery item. |

---

## Get gallery subtree

<Callout title="GET /api/v1/gallery/{item_id}/tree">
  Public.
</Callout>

Returns a gallery item plus all descendants as a flat list (max 10 levels deep). Use
`parent_id` on each item to rebuild the tree.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `item_id` | string (required) | UUID of the root gallery item. |

---

## Download a gallery asset

<Callout title="GET /api/v1/gallery/{entity_id}/download">
  Public.
</Callout>

Resolves `entity_id` as a gallery item first, then as a submission. Gallery items
serve `model.{ext}`; submissions serve `phase{N}.{ext}`.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `entity_id` | string (required) | UUID of a gallery item or submission. |

### Query Parameters

| Name | Type | Description |
| --- | --- | --- |
| `format` | string | Asset format. Values: `glb`, `fbx`, `obj`, `stl`, `usdz`, `py`, `thumbnail`, `reference_image`. Default: `glb`. |
| `index` | integer | Index for `reference_image` format. Default: `0`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -L -o model.glb \
  "https://api.thrixel.com/api/v1/gallery/abc-.../download?format=glb"
```

  </Tab>
</Tabs>


---

# Getting Started
Source: https://docs.thrixel.com/docs/getting-started

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

## What is Thrixel?

Thrixel turns text prompts and reference images into production-ready 3D models through a
five-phase pipeline. You submit a request, poll (or stream) until it's ready, then download
the result in GLB, FBX, OBJ, STL, or USDZ.

## Base URL

```bash
https://api.thrixel.com/api/v1
```

## Authentication

Authenticated endpoints require an API key passed as a Bearer token. Keys are in the
format `sk-thrixel-...` and are issued by the Thrixel team — contact us to obtain one.

```bash
Authorization: Bearer sk-thrixel-<YOUR_KEY>
```

Public endpoints (info, stream, downloads, convert, gallery) do not require authentication.

## Rate Limits

Each API key is subject to three limits (defaults shown — your plan may differ):

- **Concurrent jobs** — 3 active (queued or processing) submissions at a time
- **Hourly** — 10 requests per rolling hour
- **Daily** — 50 requests per rolling 24 hours

## Quickstart

Submit a text prompt, wait for the job to complete, and download the GLB:

<Tabs items={['curl', 'Python']}>
  <Tab value="curl">

```bash
# 1. Submit a prompt
curl -X POST https://api.thrixel.com/api/v1/phase1/submit \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"task": "a small stone gargoyle holding a lantern"}'
# → {"submission_id": "abc-123", "status": "queued", "created_at": "..."}

# 2. Poll until completed
curl https://api.thrixel.com/api/v1/abc-123/info
# → {"status": "completed", ...}

# 3. Download the GLB
curl -L -o model.glb https://api.thrixel.com/api/v1/abc-123/download?format=glb
```

  </Tab>
  <Tab value="Python">

```python
import requests, time

BASE = "https://api.thrixel.com/api/v1"
KEY = "sk-thrixel-<YOUR_KEY>"

# 1. Submit
r = requests.post(
    f"{BASE}/phase1/submit",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"task": "a small stone gargoyle holding a lantern"},
)
submission_id = r.json()["submission_id"]

# 2. Poll
while True:
    info = requests.get(f"{BASE}/{submission_id}/info").json()
    if info["status"] in ("completed", "failed"):
        break
    time.sleep(5)

# 3. Download
glb = requests.get(f"{BASE}/{submission_id}/download?format=glb")
open("model.glb", "wb").write(glb.content)
```

  </Tab>
</Tabs>


---

# Thrixel API
Source: https://docs.thrixel.com/docs

The Thrixel API turns text prompts and reference images into production-ready 3D
models through a five-phase pipeline. You submit a request, poll (or stream)
until it's ready, then download the result in GLB, FBX, OBJ, STL, or USDZ.

## Where to start

- [Getting Started](/docs/getting-started) — base URL, authentication, rate limits, and a quickstart.
- [Core Workflow](/docs/workflow) — generation endpoints (Phase 1, 2, 3, 5).
- [Track Progress](/docs/progress) — polling, streaming (SSE), and submission listing.
- [Detail & Texture](/docs/detail) — Phase 4 GPU detailing, remesh, and retexture.
- [Download & Export](/docs/download) — unified download endpoint and async conversion.
- [Organize](/docs/organize) — projects, nicknames, archive, pin.
- [Gallery](/docs/gallery) — public published models.

## Base URL

```bash
https://api.thrixel.com/api/v1
```


---

# Organize
Source: https://docs.thrixel.com/docs/organize

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

Group related submissions into projects, give them nicknames, pin favorites, and
archive older work. All endpoints below require authentication and act on resources
owned by your API key.

## Projects

---

### List projects

<Callout title="GET /api/v1/projects">
  Requires API key.
</Callout>

Returns all projects owned by the authenticated API key.

#### Query Parameters

| Name | Type | Description |
| --- | --- | --- |
| `include_archived` | boolean | Include archived projects. Default: `false`. |

#### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  https://api.thrixel.com/api/v1/projects
```

  </Tab>
</Tabs>

#### Example Response

```json
{
  "projects": [
    {
      "id": "p1q2r3s4-...",
      "name": "Gargoyle variations",
      "description": "Stylistic experiments",
      "is_archived": false,
      "created_at": "2026-04-18T09:00:00Z",
      "updated_at": "2026-04-20T14:00:00Z",
      "submission_count": 7
    }
  ],
  "count": 1
}
```

---

### Create a project

<Callout title="POST /api/v1/projects">
  Requires API key.
</Callout>

#### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `name` | string (required) | Project name. 1–255 characters. |
| `description` | string | Optional description. Max 2000 characters. |

#### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/projects \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Gargoyle variations"}'
```

  </Tab>
</Tabs>

---

### Get a project

<Callout title="GET /api/v1/projects/{project_id}">
  Requires API key.
</Callout>

Returns project metadata plus an embedded list of its submissions (soft-deleted
excluded).

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `project_id` | string (required) | UUID of the project. |

---

### Update a project

<Callout title="PATCH /api/v1/projects/{project_id}">
  Requires API key.
</Callout>

Rename or re-describe. At least one field required.

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `project_id` | string (required) | UUID of the project. |

#### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `name` | string | New name. 1–255 characters. |
| `description` | string | New description. Max 2000 characters. |

---

### Delete a project

<Callout title="DELETE /api/v1/projects/{project_id}">
  Requires API key.
</Callout>

Permanently deletes the project. Submissions in the project are unlinked (`project_id`
set to `null`) — they are not deleted.

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `project_id` | string (required) | UUID of the project. |

## Submission Management

---

### Set or clear the nickname

<Callout title="PATCH /api/v1/{submission_id}/nickname">
  Requires API key.
</Callout>

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission. |

#### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `nickname` | string \| null | Display label. Pass `null` to clear. Max 255 characters. |

---

### Archive or unarchive

<Callout title="PATCH /api/v1/{submission_id}/archive">
  Requires API key.
</Callout>

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission. |

#### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `is_archived` | boolean (required) | `true` to archive, `false` to restore. |

---

### Toggle visibility

<Callout title="PATCH /api/v1/{submission_id}/visible">
  Requires API key.
</Callout>

Hides or shows the submission in list endpoints without deleting it.

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission. |

#### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `is_visible` | boolean (required) | `true` to show, `false` to hide. |

---

### Pin or unpin

<Callout title="PATCH /api/v1/{submission_id}/pin">
  Requires API key.
</Callout>

Pinned submissions sort to the top of lists.

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission. |

#### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `is_pinned` | boolean (required) | `true` to pin, `false` to unpin. |

---

### Assign to a project

<Callout title="PATCH /api/v1/{submission_id}/project">
  Requires API key.
</Callout>

Move the submission into a project, or pass `null` to remove. Both the submission
and the target project must belong to your API key.

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission. |

#### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `project_id` | string \| null | UUID of the target project, or `null` to unassign. |

---

### Soft-delete a submission

<Callout title="DELETE /api/v1/{submission_id}">
  Requires API key.
</Callout>

Hides the submission from listings but preserves its data. Include soft-deleted items
in `/submissions` via `include_deleted=true`.

#### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID of the submission. |


---

# Track Progress
Source: https://docs.thrixel.com/docs/progress

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

Once a submission is created, monitor its lifecycle by polling `/info`, streaming
`/stream` (Server-Sent Events), or listing all your submissions.

---

## Get submission metadata

<Callout title="GET /api/v1/{submission_id}/info">
  Public.
</Callout>

Returns current status, phase, input, and parent chain. Use this for simple polling.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID returned by any submit endpoint. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl https://api.thrixel.com/api/v1/a1b2c3d4-.../info
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "submission_id": "a1b2c3d4-...",
  "phase": 1,
  "status": "completed",
  "model": "thrixel+",
  "input": {
    "type": "text",
    "task": "a small stone gargoyle holding a lantern",
    "image": null,
    "images": null,
    "modification_request": null
  },
  "parent_submission_id": null,
  "nickname": null,
  "is_archived": false,
  "is_visible": true,
  "is_deleted": false,
  "is_pinned": false,
  "adaptive_thinking": false,
  "created_at": "2026-04-20T14:32:11Z",
  "completed_at": "2026-04-20T14:34:02Z"
}
```

---

## Stream progress (SSE)

<Callout title="GET /api/v1/{submission_id}/stream">
  Public.
</Callout>

Server-Sent Events stream that emits progress updates, log messages, and status
transitions in real time. Closes automatically when the submission reaches a
terminal state.

### Path Parameters

| Name | Type | Description |
| --- | --- | --- |
| `submission_id` | string (required) | UUID returned by any submit endpoint. |

### Example Request

<Tabs items={['curl', 'JavaScript']}>
  <Tab value="curl">

```bash
curl -N https://api.thrixel.com/api/v1/a1b2c3d4-.../stream
```

  </Tab>
  <Tab value="JavaScript">

```javascript
const es = new EventSource(
  "https://api.thrixel.com/api/v1/a1b2c3d4-.../stream"
);
es.onmessage = (e) => {
  const event = JSON.parse(e.data);
  console.log(event.type, event);
};
```

  </Tab>
</Tabs>

Event frames arrive as `data:` lines containing JSON. Common shapes:

```json
// Progress update
{"type": "progress", "percent": 0.42, "message": "Generating geometry..."}

// Status change
{"type": "status", "status": "processing"}

// Terminal event — stream closes after this
{"type": "status", "status": "completed"}
```

---

## List your submissions

<Callout title="GET /api/v1/submissions">
  Requires API key.
</Callout>

Returns all submissions owned by the authenticated API key. Filter by status, phase,
or project.

### Query Parameters

| Name | Type | Description |
| --- | --- | --- |
| `status` | string | Filter by status. Values: `queued`, `processing`, `completed`, `failed`. |
| `phase` | integer | Filter by phase. Values: `1`, `2`, `3`. |
| `project_id` | string | Filter by project. |
| `include_deleted` | boolean | Include soft-deleted submissions. Default: `false`. |
| `limit` | integer | Max results. Default: `50`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  "https://api.thrixel.com/api/v1/submissions?status=completed&limit=20"
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "submissions": [
    {
      "submission_id": "a1b2c3d4-...",
      "phase": 1,
      "status": "completed",
      "nickname": null,
      "is_pinned": false,
      "project_id": null,
      "created_at": "2026-04-20T14:32:11Z"
    }
  ],
  "count": 1
}
```


---

# Core Workflow
Source: https://docs.thrixel.com/docs/workflow

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';

Generate a model from a text prompt, images, or an existing mesh. All four endpoints
return a `submission_id` that you track via the endpoints on
[Track Progress](/docs/progress).

---

## Create a model

<Callout title="POST /api/v1/phase1/submit">
  Requires API key.
</Callout>

Start a new generation from a text prompt, a reference image, or up to six images. At
least one of `task`, `image`, or `images` is required.

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `task` | string | Natural-language description of the model to create. |
| `image` | string | Single reference image — base64 data URL or HTTPS URL. |
| `images` | string[] | Up to 6 reference images (base64 or HTTPS URLs). Mutually exclusive with `image`. |
| `model` | string | LLM model override. Leave unset to use the default. |
| `project_id` | string | Group the submission under a project. |
| `adaptive_thinking` | boolean | Enable deeper reasoning pass. Slower but higher quality. Default: `false`. |

### Example Request

<Tabs items={['curl', 'Python']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/phase1/submit \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"task": "a small stone gargoyle holding a lantern"}'
```

  </Tab>
  <Tab value="Python">

```python
import requests
requests.post(
    "https://api.thrixel.com/api/v1/phase1/submit",
    headers={"Authorization": "Bearer sk-thrixel-<YOUR_KEY>"},
    json={"task": "a small stone gargoyle holding a lantern"},
)
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "submission_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "created_at": "2026-04-20T14:32:11Z"
}
```

---

## Auto-refine

<Callout title="POST /api/v1/phase2/submit">
  Requires API key.
</Callout>

Run a vision-critique pass on a completed Phase 1 or Phase 2 submission. The backend
inspects the result and produces an improved version.

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `parent_submission_id` | string (required) | ID of a completed Phase 1 or Phase 2 submission. |
| `project_id` | string | Inherit or override the parent's project. |
| `adaptive_thinking` | boolean | Enable deeper reasoning pass. Default: `false`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/phase2/submit \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"parent_submission_id": "a1b2c3d4-..."}'
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "submission_id": "b2c3d4e5-...",
  "status": "queued",
  "created_at": "2026-04-20T14:35:22Z"
}
```

---

## Modify a model

<Callout title="POST /api/v1/phase3/submit">
  Requires API key.
</Callout>

Apply a natural-language edit to an existing model. Example: "make the lantern glow blue".

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `parent_submission_id` | string (required) | ID of the submission to modify. |
| `modification_request` | string (required) | Description of the change to apply. |
| `project_id` | string | Inherit or override the parent's project. |
| `adaptive_thinking` | boolean | Enable deeper reasoning pass. Default: `false`. |

### Example Request

<Tabs items={['curl']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/phase3/submit \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_submission_id": "a1b2c3d4-...",
    "modification_request": "make the lantern glow blue"
  }'
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "submission_id": "c3d4e5f6-...",
  "status": "queued",
  "created_at": "2026-04-20T14:38:01Z"
}
```

---

## Upload an existing model

<Callout title="POST /api/v1/phase5/submit">
  Requires API key.
</Callout>

Bring your own GLB file into Thrixel so you can run Phase 2, 3, or 4 operations on it.
Multipart form upload, max 100 MB.

### Request Body

| Name | Type | Description |
| --- | --- | --- |
| `glb_file` | file (required) | Binary `.glb` file (`Content-Type: multipart/form-data`). |
| `task` | string | Optional label describing the uploaded model. Max 2000 chars. |
| `project_id` | string | Assign to a project. |

### Example Request

<Tabs items={['curl', 'Python']}>
  <Tab value="curl">

```bash
curl -X POST https://api.thrixel.com/api/v1/phase5/submit \
  -H "Authorization: Bearer sk-thrixel-<YOUR_KEY>" \
  -F "glb_file=@./my_model.glb" \
  -F "task=hand-sculpted base mesh"
```

  </Tab>
  <Tab value="Python">

```python
import requests
requests.post(
    "https://api.thrixel.com/api/v1/phase5/submit",
    headers={"Authorization": "Bearer sk-thrixel-<YOUR_KEY>"},
    files={"glb_file": open("my_model.glb", "rb")},
    data={"task": "hand-sculpted base mesh"},
)
```

  </Tab>
</Tabs>

### Example Response

```json
{
  "submission_id": "d4e5f6a7-...",
  "status": "completed",
  "original_filename": "my_model.glb",
  "file_size_bytes": 4528192,
  "created_at": "2026-04-20T14:40:15Z"
}
```


---