BitSoul3D Engine API

BASE=https://bitsoulhosting.com/marketplace/api
KEY=your_api_key
UA="MyStudioApp/1.0 ([email protected])"

# 1. Create a job — credits are reserved now, refunded if it fails
curl -s -A "$UA" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"op":"text-to-3d","prompt":"a weathered bronze compass, game prop","quality":"standard","visibility":"private"}' \
  "$BASE/gen/create"
# → {"task_id":"6f1c2d…","cost":20,"status":"running"}

# 2. Poll every 3 seconds until status is "done" or "failed"
TASK=6f1c2d…
while true; do
  BODY=$(curl -s -A "$UA" -H "X-API-Key: $KEY" "$BASE/gen/task/$TASK")
  echo "$BODY" | grep -q '"status":"running"' || break
  sleep 3
done
echo "$BODY"
# → {"task_id":"…","op":"text-to-3d","status":"done","progress":100,"cost":20,
#    "files":[{"name":"model.glb","file":"…","bytes":2481920,"mime":"model/gltf-binary"}]}

# 3. Download file 0
curl -s -A "$UA" -H "X-API-Key: $KEY" -o compass.glb "$BASE/gen/file/$TASK/0"

// Node 18+ (built-in fetch). In a browser, drop the fs and User-Agent lines — the browser sets its own.
import fs from 'node:fs/promises';

const BASE = 'https://bitsoulhosting.com/marketplace/api';
const H = { 'X-API-Key': process.env.BS3D_KEY, 'Content-Type': 'application/json', 'User-Agent': 'MyStudioApp/1.0 ([email protected])' };
const sleep = ms => new Promise(r => setTimeout(r, ms));

async function create(body) {
  for (let attempt = 0; attempt < 6; attempt++) {
    const r = await fetch(`${BASE}/gen/create`, { method: 'POST', headers: H, body: JSON.stringify(body) });
    const j = await r.json();
    if (r.ok) return j;                                         // { task_id, cost, status: 'running' }
    if (r.status === 429 && j.retry_after) { await sleep(j.retry_after * 1000); continue; }  // lane busy — nothing charged
    throw Object.assign(new Error(j.error || `HTTP ${r.status}`), { status: r.status, data: j });
  }
  throw new Error('The engine stayed busy — try again in a minute.');
}

async function waitFor(taskId) {
  let errors = 0;
  for (;;) {
    await sleep(3000);
    const r = await fetch(`${BASE}/gen/task/${taskId}`, { headers: H });
    if (!r.ok) { if (++errors >= 20) throw new Error('Lost track of the job'); continue; }
    const t = await r.json(); errors = 0;
    if (t.status === 'done') return t;
    if (t.status === 'failed') throw new Error(t.error || 'Job failed — credits refunded');
    console.log(`${t.progress}%`);
  }
}

async function download(taskId, n = 0) {
  const r = await fetch(`${BASE}/gen/file/${taskId}/${n}`, { headers: H });
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  return Buffer.from(await r.arrayBuffer());
}

const { task_id } = await create({ op: 'text-to-3d', prompt: 'a weathered bronze compass, game prop', quality: 'standard', visibility: 'private' });
const task = await waitFor(task_id);
await fs.writeFile(task.files[0].name, await download(task_id, 0));   // model.glb

# Python 3.8+ with the requests package (pip install requests).
# The explicit User-Agent matters: the package's default string is blocked at our edge.
import os, time, requests

BASE = 'https://bitsoulhosting.com/marketplace/api'
H = {'X-API-Key': os.environ['BS3D_KEY'], 'User-Agent': 'MyStudioApp/1.0 ([email protected])'}

def create(body):
    for _ in range(6):
        r = requests.post(f'{BASE}/gen/create', json=body, headers=H, timeout=60)
        j = r.json()
        if r.ok:
            return j                                   # {'task_id': ..., 'cost': 20, 'status': 'running'}
        if r.status_code == 429 and j.get('retry_after'):
            time.sleep(j['retry_after']); continue      # lane busy — nothing charged
        raise RuntimeError(f"{r.status_code}: {j.get('error')}")
    raise RuntimeError('The engine stayed busy — try again in a minute.')

def wait_for(task_id):
    errors = 0
    while True:
        time.sleep(3)
        r = requests.get(f'{BASE}/gen/task/{task_id}', headers=H, timeout=60)
        if not r.ok:
            errors += 1
            if errors >= 20: raise RuntimeError('Lost track of the job')
            continue
        t = r.json(); errors = 0
        if t['status'] == 'done': return t
        if t['status'] == 'failed': raise RuntimeError(t.get('error') or 'Job failed — credits refunded')
        print(f"{t.get('progress', 0)}%")

def download(task_id, n=0):
    r = requests.get(f'{BASE}/gen/file/{task_id}/{n}', headers=H, timeout=300)
    r.raise_for_status()
    return r.content

job = create({'op': 'text-to-3d', 'prompt': 'a weathered bronze compass, game prop', 'quality': 'standard', 'visibility': 'private'})
task = wait_for(job['task_id'])
with open(task['files'][0]['name'], 'wb') as f:
    f.write(download(job['task_id'], 0))                  # model.glb

# Image → image_token → image-to-3d
curl -s -A "$UA" -H "X-API-Key: $KEY" -H "Content-Type: image/png" \
  --data-binary @photo.png "$BASE/gen/upload"
# → {"image_token":"…"}
curl -s -A "$UA" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"op":"image-to-3d","image_token":"…","quality":"standard"}' "$BASE/gen/create"

# Model → model_token → import (free) → rig
curl -s -A "$UA" -H "X-API-Key: $KEY" -H "Content-Type: model/gltf-binary" \
  --data-binary @hero.glb "$BASE/gen/upload-model"
# → {"model_token":"…"}
# FBX / OBJ / STL: name the extension and send octet-stream
curl -s -A "$UA" -H "X-API-Key: $KEY" -H "Content-Type: application/octet-stream" \
  --data-binary @hero.fbx "$BASE/gen/upload-model?ext=fbx"
curl -s -A "$UA" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"op":"import","model_token":"…"}' "$BASE/gen/create"
# poll that task to done, then:
curl -s -A "$UA" -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"op":"rig","input":"IMPORT_TASK_ID","rig_type":"biped","spec":"native","out_format":"glb","library":"current"}' "$BASE/gen/create"

const AUTH = { 'X-API-Key': process.env.BS3D_KEY, 'User-Agent': 'MyStudioApp/1.0 ([email protected])' };

async function uploadImage(path) {                      // PNG or JPEG
  const bytes = await fs.readFile(path);
  const type = /\.jpe?g$/i.test(path) ? 'image/jpeg' : 'image/png';
  const r = await fetch(`${BASE}/gen/upload`, { method: 'POST', headers: { ...AUTH, 'Content-Type': type }, body: bytes });
  const j = await r.json(); if (!r.ok) throw new Error(j.error);
  return j.image_token;
}

async function uploadModel(path) {                      // GLB, or FBX / OBJ / STL via ?ext=
  const bytes = await fs.readFile(path);
  const ext = path.split('.').pop().toLowerCase();
  const q = ext === 'glb' ? '' : `?ext=${ext}`;
  const r = await fetch(`${BASE}/gen/upload-model${q}`, { method: 'POST',
    headers: { ...AUTH, 'Content-Type': ext === 'glb' ? 'model/gltf-binary' : 'application/octet-stream' }, body: bytes });
  const j = await r.json(); if (!r.ok) throw new Error(j.error);
  return j.model_token;
}

// Photo → 3D
const image_token = await uploadImage('photo.png');
const model = await waitFor((await create({ op: 'image-to-3d', image_token, quality: 'standard' })).task_id);

// Your own model → import (free) → rig
const model_token = await uploadModel('hero.glb');
const imported = await waitFor((await create({ op: 'import', model_token })).task_id);
const rigged = await waitFor((await create({ op: 'rig', input: imported.task_id, rig_type: 'biped', spec: 'native', out_format: 'glb', library: 'current' })).task_id);

def upload_image(path):                                 # PNG or JPEG
    ctype = 'image/jpeg' if path.lower().endswith(('.jpg', '.jpeg')) else 'image/png'
    with open(path, 'rb') as f:
        r = requests.post(f'{BASE}/gen/upload', data=f.read(), headers={**H, 'Content-Type': ctype}, timeout=120)
    r.raise_for_status()
    return r.json()['image_token']

def upload_model(path):                                 # GLB, or FBX / OBJ / STL via ?ext=
    ext = path.rsplit('.', 1)[-1].lower()
    url = f'{BASE}/gen/upload-model' + ('' if ext == 'glb' else f'?ext={ext}')
    ctype = 'model/gltf-binary' if ext == 'glb' else 'application/octet-stream'
    with open(path, 'rb') as f:
        r = requests.post(url, data=f.read(), headers={**H, 'Content-Type': ctype}, timeout=600)
    r.raise_for_status()
    return r.json()['model_token']

# Photo → 3D
token = upload_image('photo.png')
model = wait_for(create({'op': 'image-to-3d', 'image_token': token, 'quality': 'standard'})['task_id'])

# Your own model → import (free) → rig
model_token = upload_model('hero.glb')
imported = wait_for(create({'op': 'import', 'model_token': model_token})['task_id'])
rigged = wait_for(create({'op': 'rig', 'input': imported['task_id'], 'rig_type': 'biped',
                          'spec': 'native', 'out_format': 'glb', 'library': 'current'})['task_id'])