API_REFERENCE.md

# EntropyDrop API surface (reverse-engineered from a HAR capture, 2026-09-13)

Documented for reference only. **This Space does not call any of it** — it runs
everything locally. Use this if you later want a hybrid Space that submits to
their API instead of running Flux, or if you want to understand their pipeline
naming.

Base URL: `https://api.entropydrop.com` · CDN: `https://cdn.entropydrop.com`
Auth: `Authorization: Bearer <token>` (Google sign-in; `POST /skin/api/auth/refresh`).
Origin `https://entropydrop.com` — CORS preflight (`OPTIONS`) precedes each call.

## Endpoints observed

| Method | Path | Purpose |
|---|---|---|
| POST | `/skin/api/generate` | Submit a generation (multipart) |
| GET | `/skin/api/models` | Available model versions |
| GET | `/skin/api/generation_credit_cost` | Credit price of one generation |
| GET | `/skin/api/logs/<ID>` | Poll a generation's status/result |
| GET | `/skin/api/logs/<ID>/derived` | Child generations (edits) |
| GET | `/skin/api/logs/<ID>/collections` | Collections containing it |
| GET | `/skin/api/logs/<ID>/public_collections` | Public collections |
| GET | `/skin/api/history` | User's generation history |
| GET | `/skin/api/discovery` | Public gallery |
| GET | `/skin/api/users/me` | Current user |
| GET | `/skin/api/forum/notifications` | Forum notifications |
| POST | `/skin/api/auth/refresh` | Refresh the bearer token |

Generation IDs are 16 uppercase alphanumerics, e.g. `5EEF3PRRKHFH12DC`.

## `POST /skin/api/generate`

`multipart/form-data`, observed fields:

| Field | Example | Notes |
|---|---|---|
| `file` | `sonaref1.jpg` | the reference image |
| `mode` | `aigc_image_to_skin` | pipeline selector |
| `is_public` | `true` | public generations are eligible for their dataset |
| `model_version` | `sking_v73_flux_4b_000027000` | or `SKING_DDJ_v104b` |
| `seed` | `29976038` | |
| `n_step` | `100` | **100 in every record observed** |
| `guidance` | `4` | **4.0 in every record observed** |

Response is an async ack, not the image:

```json
{"id": "5EEF3PRRKHFH12DC", "status": "pending", "message": "Task queued"}
```

Then poll `GET /skin/api/logs/<id>` until `status` becomes `success`.

## `GET /skin/api/models`

```json
{"text_to_image_models": ["z_image"],
 "image_edit_models": ["flux_4b"],
 "image_to_skin_models": ["SKING_DDJ_v104b", "sking_v73_flux_4b_000027000"]}
```

## `GET /skin/api/logs/<id>` — record shape

```json
{
  "id": "ZNU125D1THWZTHE6",
  "name": "Untitled",
  "prompt": null,
  "mode": "aigc_image_to_skin",
  "result": "https://cdn.entropydrop.com/generations/<ID>.png",
  "source": "https://cdn.entropydrop.com/uploads/<ID>.png",
  "edited_image_url": null,
  "image_to_skin_edited_image_url":
      "https://cdn.entropydrop.com/real_to_render_intermediate/<ID>.png",
  "is_public": true,
  "status": "success",
  "error_msg": null,
  "creator": {"id": "...", "username": "...", "avatar_url": "...", "skin_url": null},
  "timestamp": "2026-09-13T10:03:04.529708Z",
  "likes_count": 0,
  "is_liked": false,
  "model_version": "SKING_DDJ_v104b",
  "parent": null,
  "seed": 40491355,
  "n_step": 100,
  "guidance": 4.0,
  "queue_position": 0,
  "is_pro": false,
  "license": {"code": "cc-by-nc-4.0", "public_license": "cc-by-nc-4.0",
              "version": 1, "granted_at": "...",
              "commercial_licensee_user_id": null},
  "has_feedback": false
}
```

## What the records reveal about their pipeline

`image_to_skin_edited_image_url` is the key field — it is the **stage-1
intermediate**, and it is only populated for some model versions:

| `model_version` | `image_to_skin_edited_image_url` | Interpretation |
|---|---|---|
| `SKING_DDJ_v104b` | `…/real_to_render_intermediate/<id>.png` (1024×1024) | **two-stage**: real→render via the external provider, then render→UV. Matches the `entropydrop_real_to_render_worker` repo exactly, including the `real_to_render_intermediate/` S3 prefix named in its README. |
| `sking_v73_flux_4b_000027000` | `null` | the older local-Flux path; intermediate not persisted |
| `SKING_DDJ_v54` | `…/real_to_render_intermediate/<id>.png` | two-stage, older parser |

Observed counts across 185 records in the capture: `SKING_DDJ_v104b` ×134,
`sking_v73_flux_4b_000027000` ×2, `SKING_DDJ_v54` ×1 (the rest have no
`model_version` — gallery/discovery entries).

**`SKING_DDJ_v104b` is not published.** Their HF org contains exactly one model
repo (`EntropyDrop/Sking`) whose newest bundle is `SKING_DDJ_v104`, released
2026-09-08 — five days before this capture. There is no `v104b` on their HF
org, and no LoRA newer than `sking_v73`. That is the single largest fidelity gap
between this Space and the live site.

## CDN layout

```
https://cdn.entropydrop.com/uploads/<ID>.png                      original upload
https://cdn.entropydrop.com/real_to_render_intermediate/<ID>.png  stage-1 render
https://cdn.entropydrop.com/generations/<ID>.png                  final 64×64 skin
https://entropydrop-skin.s3.us-east-2.amazonaws.com/generations/…  backing bucket (us-east-2)
```

Public generations are directly fetchable without auth, which is how
`testdata/` was assembled.

## Credits and licensing

- `GET /skin/api/generation_credit_cost` → `{"credits": 4, "is_pro": false,
  "under_maintenance": false}`
- Every generation record carries `"license": {"code": "cc-by-nc-4.0"}` —
  outputs are **non-commercial** by default, with a
  `commercial_licensee_user_id` field implying a separate commercial license
  exists.

If you build anything on top of their API or reuse their generated images,
respect that CC BY-NC 4.0 term.