Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
// SculptForge - open source digital sculpting
// SPDX-License-Identifier: GPL-3.0-or-later
#include "ai/Hyper3D.h"
#include "ai/AiPolicy.h"
#include "ai/Http.h"
#include "ai/ImageTo3DService.h"
#include "core/AuditLog.h"
#include "core/Json.h"
#include "core/NetworkPolicy.h"
#include <algorithm>
#include <cctype>
#include <chrono>
#include <cstdint>
#include <cstdlib>
#include <filesystem>
#include <fstream>
#include <random>
#include <thread>
#if !defined(_WIN32)
#include <unistd.h>
#endif
namespace sf::ai::hyper3d {
namespace {
constexpr int kMaxMinutes = 20;
constexpr int kTimeoutSeconds = 60;
Transport gTransport; // (tests)
std::vector<int>* gWaits = nullptr;
size_t gMaxBytes = kMaxDownloadBytes;
void status(GenerationProgress* p, const std::string& text, int percent = -1) {
if (!p) return;
p->setStatus(text);
p->percent = percent;
}
bool wait(GenerationProgress* p, int seconds) {
if (gTransport) {
if (gWaits) gWaits->push_back(seconds);
return !(p && p->cancel);
}
for (int i = 0; i < seconds * 10; ++i) {
if (p && p->cancel) return false;
std::this_thread::sleep_for(std::chrono::milliseconds(100));
}
return !(p && p->cancel);
}
bool hostUnder(const std::string& host, const char* domain) {
const std::string d = domain;
return host == d || (host.size() > d.size() && host.compare(host.size() - d.size(), d.size(), d) == 0 &&
host[host.size() - d.size() - 1] == '.');
}
// Hyper3D answers application errors with HTTP 201 and {"error": CODE, "message": ...}.
std::string bodyError(const Json& j) {
const std::string code = j["error"].isString() ? j["error"].asString() : std::string();
if (code.empty()) return {};
const std::string msg = j["message"].isString() ? j["message"].asString().substr(0, 200) : std::string();
if (code == "API_INSUFFICIENT_FUNDS") return "Out of credits on your Hyper3D account";
if (code == "API_NO_ACTIVE_SUBSCRIPTION") return "Your Hyper3D account has no active API subscription";
if (code == "API_SUBSCRIPTION_PLAN_TOO_LOW")
return "Your Hyper3D plan doesn't include this tier (Basic API access covers Extreme-Low and Low)";
if (code == "API_PARALLELISM_LIMIT_REACHED") return "Hyper3D is already running your other generations - try again shortly";
if (code == "API_OBJECT_NOT_FOUND_ON_IMAGE") return "Hyper3D found no object in the image";
if (code == "IMAGE_CONTENT_VIOLATION") return "Hyper3D refused the content";
return "Hyper3D: " + code.substr(0, 60) + (msg.empty() ? std::string() : " (" + msg + ")");
}
std::string httpError(const HttpResponse& r) {
if (!r.error.empty()) return "Could not reach Hyper3D: " + r.error;
switch (r.status) {
case 401:
case 403: return "Hyper3D rejected the API key";
case 429: return "Hyper3D is rate limiting - wait a moment and try again";
default: return "Hyper3D answered HTTP " + std::to_string(r.status);
}
}
// One API call: a POST to exactly kApiBase + path, the key only here.
HttpResponse post(const std::string& key, const std::string& path, const std::string& contentType, const std::string& body) {
const std::string url = std::string(kApiBase) + path;
if (!apiUrl(url)) {
HttpResponse r;
r.error = "refused";
return r;
}
const std::vector<std::string> headers = {"Authorization: Bearer " + key, contentType, "Accept: application/json"};
if (gTransport) return gTransport("POST", url, headers, body);
return httpPostNoRedirect(url, headers, body, kTimeoutSeconds);
}
uint32_t le32(const std::string& b, size_t at) {
return uint32_t(uint8_t(b[at])) | uint32_t(uint8_t(b[at + 1])) << 8 | uint32_t(uint8_t(b[at + 2])) << 16 |
uint32_t(uint8_t(b[at + 3])) << 24;
}
} // namespace
const std::vector<Tier>& tiers() {
static const std::vector<Tier> t = {
{"Gen-2.5-Extreme-Low", "Gen-2.5 Extreme Low (fastest)"},
{"Gen-2.5-Low", "Gen-2.5 Low"},
{"Gen-2.5-Medium", "Gen-2.5 Medium"},
{"Gen-2.5-High", "Gen-2.5 High"},
{"Gen-2.5-Extreme-High", "Gen-2.5 Extreme High (more credits)"},
};
return t;
}
std::string resolvedTier(const std::string& tier) {
for (const Tier& t : tiers())
if (tier == t.id) return tier;
return kDefaultTier;
}
bool apiUrl(const std::string& url) {
net::UrlParts u;
if (!net::parseUrl(url, u) || u.scheme != "https" || u.host != kApiHost || u.port != 443) return false;
return u.path.rfind("/api/v2/", 0) == 0 && u.path.find("..") == std::string::npos;
}
bool downloadUrlAllowed(const std::string& url) {
net::UrlParts u;
if (!net::parseUrl(url, u) || u.scheme != "https" || u.port != 443) return false;
return hostUnder(u.host, "hyper3d.com") || hostUnder(u.host, "hyper3d.ai") || hostUnder(u.host, "deemos.com");
}
std::string submitBody(const std::string& tier, const std::string& png, const std::string& prompt,
std::string& contentTypeHeader) {
std::vector<MultipartField> fields;
if (!png.empty()) fields.push_back({"images", png, "input.png", "image/png"});
else fields.push_back({"prompt", prompt.substr(0, 800)});
fields.push_back({"tier", resolvedTier(tier)});
fields.push_back({"geometry_file_format", "glb"});
fields.push_back({"material", "None"}); // the shape is what we sculpt
fields.push_back({"mesh_mode", "Raw"});
return multipartBody(fields, contentTypeHeader);
}
bool parseSubmit(const std::string& body, std::string& taskUuid, std::string& subscriptionKey, std::string& error) {
Json j;
std::string err;
if (!Json::parse(body, j, err) || !j.isObject()) return (error = "Unexpected reply from Hyper3D", false);
if (std::string e = bodyError(j); !e.empty()) return (error = e, false);
taskUuid = j["uuid"].asString();
subscriptionKey = j["jobs"]["subscription_key"].asString();
if (taskUuid.empty() || subscriptionKey.empty()) return (error = "Unexpected reply from Hyper3D", false);
return true;
}
bool parseStatus(const std::string& body, JobState& state, int& queue, std::string& error) {
Json j;
std::string err;
queue = -1;
if (!Json::parse(body, j, err) || !j.isObject()) return (error = "Unexpected reply from Hyper3D", false);
if (std::string e = bodyError(j); !e.empty()) return (error = e, false);
if (!j["jobs"].isArray() || j["jobs"].size() == 0) return (error = "Unexpected reply from Hyper3D", false);
bool allDone = true, anyGenerating = false;
for (const Json& job : j["jobs"].items()) {
const std::string s = job["status"].asString();
if (s == "Failed") return (state = JobState::Failed, true);
if (s != "Done") allDone = false;
if (s == "Generating") anyGenerating = true;
if (job["queue_length"].isNumber()) queue = int(job["queue_length"].asNumber());
}
if (j["queue_length"].isNumber()) queue = int(j["queue_length"].asNumber());
state = allDone ? JobState::Done : anyGenerating ? JobState::Generating : JobState::Waiting;
return true;
}
bool parseDownload(const std::string& body, std::string& url, std::string& error) {
Json j;
std::string err;
if (!Json::parse(body, j, err) || !j.isObject()) return (error = "Unexpected reply from Hyper3D", false);
if (std::string e = bodyError(j); !e.empty()) return (error = e, false);
for (const Json& f : j["list"].items()) {
std::string name = f["name"].asString();
std::transform(name.begin(), name.end(), name.begin(), [](unsigned char c) { return char(std::tolower(c)); });
if (name.size() > 4 && name.compare(name.size() - 4, 4, ".glb") == 0 && f["url"].isString()) {
url = f["url"].asString();
return true;
}
}
return (error = "Hyper3D finished but returned no GLB", false);
}
int pollDelaySeconds(int attempt) {
static const int steps[] = {5, 5, 7, 10, 15, 20, 30};
return attempt < int(std::size(steps)) ? steps[std::max(attempt, 0)] : 30;
}
bool checkGlb(const std::string& b, std::string& error) {
error = "The downloaded file is not a valid GLB model";
if (b.size() < 20 || b.size() > gMaxBytes) return false;
if (b.compare(0, 4, "glTF") != 0 || le32(b, 4) != 2 || le32(b, 8) != b.size()) return false;
size_t at = 12;
bool first = true;
while (at < b.size()) {
if (b.size() - at < 8) return false;
const uint64_t len = le32(b, at);
const uint32_t type = le32(b, at + 4);
if (len % 4 != 0 || len > b.size() - at - 8) return false;
if (first) {
if (type != 0x4E4F534Au || len == 0) return false; // "JSON"
Json j;
std::string err;
if (!Json::parse(b.substr(at + 8, size_t(len)), j, err) || !j.isObject() || !j["asset"].isObject()) return false;
first = false;
}
at += 8 + size_t(len);
}
if (first) return false;
error.clear();
return true;
}
std::string makePrivateDir(std::string& error) {
std::error_code ec;
const std::filesystem::path base = std::filesystem::temp_directory_path(ec);
if (ec) return (error = "No temporary folder: " + ec.message(), std::string());
#if defined(_WIN32)
// (the temp folder is the user's own, under %LOCALAPPDATA%)
std::random_device rd;
for (int i = 0; i < 16; ++i) {
const std::filesystem::path dir = base / ("sculptforge-hyper3d-" + std::to_string(rd()) + std::to_string(rd()));
if (std::filesystem::create_directory(dir, ec)) {
const auto u8 = dir.u8string();
return std::string(u8.begin(), u8.end());
}
}
error = "Could not make a temporary folder";
return {};
#else
std::string templ = (base / "sculptforge-hyper3d-XXXXXX").string();
if (!mkdtemp(templ.data())) return (error = "Could not make a temporary folder", std::string()); // (mode 0700)
return templ;
#endif
}
GeneratorResult run(const AiSettings& s, const std::string& imagePath, const std::string& prompt, GenerationProgress* p) {
GeneratorResult result;
const bool text = imagePath.empty();
const std::string tier = resolvedTier(s.hyper3dTier);
const auto start = std::chrono::steady_clock::now();
// Gates before anything is sent: the AI switch, the studio policy, the audit log when it is required.
if (!aiRequestAllowed("hyper3d", std::string(kApiBase) + "/rodin", result.error)) return result;
const std::string key = s.resolvedHyper3dKey();
if (key.empty()) {
result.error = "Add your Hyper3D API key (hyper3d.ai > API dashboard) in Generate 3D";
return result;
}
if (std::string why; audit::required() && !audit::writable(&why)) {
result.error = why;
return result;
}
auto record = [&](const GeneratorResult& r) {
audit::Entry e;
e.tool = "ai";
e.command = text ? "text_to_3d" : "image_to_3d";
e.args.set("service", "hyper3d");
e.args.set("tier", tier);
if (text) e.args.set("promptChars", double(prompt.size())); // (the length, not the words)
e.ok = r.ok;
e.message = r.ok ? "Model downloaded" : r.error;
e.endpoint = kApiHost;
e.ms = std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::steady_clock::now() - start).count();
audit::record(e);
};
auto fail = [&](std::string error) {
result = {};
result.error = std::move(error);
record(result);
return result;
};
std::string png;
if (!text) {
std::string err;
if (!prepareImagePng(imagePath, png, err)) {
result.error = err;
return result;
}
} else if (prompt.find_first_not_of(" \t\r\n") == std::string::npos) {
result.error = "Describe the model you want";
return result;
}
status(p, "Sending to Hyper3D Rodin...");
std::string contentType;
const std::string body = submitBody(tier, png, prompt, contentType);
const HttpResponse submitted = post(key, "/rodin", contentType, body);
if (!submitted.error.empty() || submitted.status < 200 || submitted.status >= 300) return fail(httpError(submitted));
std::string taskUuid, subscriptionKey, err;
if (!parseSubmit(submitted.body, taskUuid, subscriptionKey, err)) return fail(err);
Json statusBody = Json::object();
statusBody.set("subscription_key", subscriptionKey);
for (int attempt = 0;; ++attempt) {
if (!wait(p, pollDelaySeconds(attempt)))
return fail("Cancelled (the Hyper3D task keeps running on your account)");
if (std::chrono::steady_clock::now() - start > std::chrono::minutes(kMaxMinutes))
return fail("Timed out waiting for Hyper3D");
const HttpResponse st = post(key, "/status", "Content-Type: application/json", statusBody.dump());
if (!st.error.empty() || st.status == 429 || st.status >= 500) continue; // transient: back off and ask again
if (st.status < 200 || st.status >= 300) return fail(httpError(st));
JobState state;
int queue = -1;
if (!parseStatus(st.body, state, queue, err)) return fail(err);
const int secs = int(std::chrono::duration_cast<std::chrono::seconds>(std::chrono::steady_clock::now() - start).count());
if (state == JobState::Failed) return fail("Hyper3D could not make this model");
if (state == JobState::Done) break;
status(p, state == JobState::Waiting
? "Waiting in queue" + (queue >= 0 ? " (" + std::to_string(queue) + " ahead)" : std::string()) + "... " +
std::to_string(secs) + "s"
: "Generating 3D model... " + std::to_string(secs) + "s");
}
Json downloadBody = Json::object();
downloadBody.set("task_uuid", taskUuid);
const HttpResponse listed = post(key, "/download", "Content-Type: application/json", downloadBody.dump());
if (!listed.error.empty() || listed.status < 200 || listed.status >= 300) return fail(httpError(listed));
std::string fileUrl;
if (!parseDownload(listed.body, fileUrl, err)) return fail(err);
// A refused host: the paid result isn't lost, it stays in the user's Hyper3D account under this task id.
auto refusedHost = [&](const std::string& host) {
std::string id;
for (char c : taskUuid.substr(0, 64))
if (std::isalnum(static_cast<unsigned char>(c)) || c == '-') id += c;
return fail("Refused the model file: it isn't on Hyper3D's servers (" + host +
"). The model stays in your Hyper3D account (hyper3d.ai dashboard), task " + id);
};
if (!downloadUrlAllowed(fileUrl)) {
net::UrlParts u;
return refusedHost(net::parseUrl(fileUrl, u) ? u.host : std::string("not an https address"));
}
if (!aiRequestAllowed("hyper3d", fileUrl, err)) return fail(err);
// The file: no key sent, Hyper3D's hosts only (each redirect too), capped, then checked before anyone parses it.
status(p, "Downloading model...");
std::string bytes;
bool tooBig = false;
auto get = [&](const std::string& url, const std::function<bool(const std::string&)>& allowed, int stall,
const std::function<bool(const char*, size_t)>& onData,
const std::function<bool(uint64_t, uint64_t)>& onProgress) {
if (!gTransport) return httpGetRestricted(url, allowed, stall, onData, onProgress);
HttpResponse r = gTransport("GET", url, {}, {});
if (!r.body.empty() && !onData(r.body.data(), r.body.size())) r.error = "stopped";
r.body.clear();
return r;
};
const HttpResponse got = get(
fileUrl, [](const std::string& u) { return downloadUrlAllowed(u); }, kTimeoutSeconds,
[&](const char* d, size_t n) {
if (bytes.size() + n > gMaxBytes) return (tooBig = true, false);
bytes.append(d, n);
return true;
},
[&](uint64_t received, uint64_t total) {
if (total > gMaxBytes) return (tooBig = true, false);
if (p && total > 0) p->percent = int(received * 100 / total);
return !(p && p->cancel);
});
if (tooBig) return fail("The model file is larger than 200 MB - refused");
if (p && p->cancel) return fail("Cancelled");
if (got.error.rfind("refused to download from ", 0) == 0) { // (a redirect left Hyper3D's servers)
net::UrlParts u;
const std::string to = got.error.substr(25);
return refusedHost(net::parseUrl(to, u) ? u.host : std::string("not an https address"));
}
if (!got.error.empty() || got.status != 200) return fail("Download failed: " + (got.error.empty() ? "HTTP " + std::to_string(got.status) : got.error));
if (!checkGlb(bytes, err)) return fail(err);
const std::string dir = makePrivateDir(err);
if (dir.empty()) return fail(err);
const std::string path = dir + "/model.glb";
{
std::ofstream f(std::filesystem::path(std::u8string(path.begin(), path.end())), std::ios::binary);
if (!f || !f.write(bytes.data(), std::streamsize(bytes.size()))) {
f.close();
std::error_code ec;
std::filesystem::remove_all(std::filesystem::path(std::u8string(dir.begin(), dir.end())), ec);
return fail("Cannot write the model file");
}
}
result = {};
result.ok = true;
result.outputPath = path;
result.privateDir = dir;
record(result);
return result;
}
void setMaxDownloadBytesForTests(size_t bytes) { gMaxBytes = bytes ? bytes : kMaxDownloadBytes; }
void setTransportForTests(Transport transport, std::vector<int>* waits) {
gTransport = std::move(transport);
gWaits = waits;
}
} // namespace sf::ai::hyper3d