Driving H3 Prompt Studio from code

# Every call is Bearer-authenticated against the app API.
BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="YOUR_TOKEN"

call() {   # call METHOD PATH [JSON]
  curl -sS -X "$1" "$BASE$2" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    ${3:+-d "$3"}
}

import json, urllib.request

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"

def call(method, path, body=None, headers=None):
    data = json.dumps(body).encode() if body is not None else None
    req  = urllib.request.Request(BASE + path, data=data, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    for k, v in (headers or {}).items():
        req.add_header(k, v)
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

const BASE  = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN";

async function call(method, path, body, headers = {}) {
  const res = await fetch(BASE + path, {
    method,
    headers: {
      "Authorization": `Bearer ${TOKEN}`,
      "Content-Type": "application/json",
      ...headers
    },
    body: body === undefined ? undefined : JSON.stringify(body)
  });
  const json = await res.json();
  if (!json.ok) throw new Error(json.error.code + ": " + json.error.message);
  return json.data;
}

package main

import (
    "bytes"
    "encoding/json"
    "io"
    "net/http"
)

const base = "https://api.skillsafe.ai/v1/app-api"
const token = "YOUR_TOKEN"

func call(method, path string, body any) (map[string]any, error) {
    var rdr io.Reader
    if body != nil {
        b, _ := json.Marshal(body)
        rdr = bytes.NewReader(b)
    }
    req, _ := http.NewRequest(method, base+path, rdr)
    req.Header.Set("Authorization", "Bearer "+token)
    req.Header.Set("Content-Type", "application/json")
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer res.Body.Close()
    var out map[string]any
    return out, json.NewDecoder(res.Body).Decode(&out)
}

import java.net.URI;
import java.net.http.*;

class Client {
    static final String BASE  = "https://api.skillsafe.ai/v1/app-api";
    static final String TOKEN = "YOUR_TOKEN";
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String call(String method, String path, String body) throws Exception {
        HttpRequest.BodyPublisher pub = body == null
            ? HttpRequest.BodyPublishers.noBody()
            : HttpRequest.BodyPublishers.ofString(body);
        HttpRequest req = HttpRequest.newBuilder(URI.create(BASE + path))
            .header("Authorization", "Bearer " + TOKEN)
            .header("Content-Type", "application/json")
            .method(method, pub)
            .build();
        return HTTP.send(req, HttpResponse.BodyHandlers.ofString()).body();
    }
}

require "json"
require "net/http"
require "uri"

BASE  = "https://api.skillsafe.ai/v1/app-api"
TOKEN = "YOUR_TOKEN"

def call(method, path, body = nil)
  uri = URI(BASE + path)
  klass = Net::HTTP.const_get(method.capitalize)
  req = klass.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  req["Content-Type"]  = "application/json"
  req.body = JSON.generate(body) if body
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  JSON.parse(res.body)
end

<?php
const BASE  = "https://api.skillsafe.ai/v1/app-api";
const TOKEN = "YOUR_TOKEN";

function call(string $method, string $path, ?array $body = null): array {
    $ch = curl_init(BASE . $path);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer " . TOKEN,
        "Content-Type: application/json",
    ]);
    if ($body !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    $out = curl_exec($ch);
    curl_close($ch);
    return json_decode($out, true);
}

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

static class Client {
    const string Base  = "https://api.skillsafe.ai/v1/app-api";
    const string Token = "YOUR_TOKEN";
    static readonly HttpClient Http = new HttpClient();

    public static async Task<JsonDocument> Call(HttpMethod method, string path, object body = null) {
        var req = new HttpRequestMessage(method, Base + path);
        req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Token);
        if (body != null)
            req.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
        var res = await Http.SendAsync(req);
        return JsonDocument.Parse(await res.Content.ReadAsStringAsync());
    }
}

# A guest token is enough for /me and /estimate. Writing a package needs a
# personal token: open https://minimax-h3-prompt.skillsafe.ai/tokens.html and
# use "Copy shell export".
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug":"minimax-h3-prompt"}' 

# Guest token: enough for /me and /estimate.
guest = call("POST", "/guest", {"slug": "minimax-h3-prompt"})
TOKEN = guest["data"]["token"]

# For a metered run use a personal token from
# https://minimax-h3-prompt.skillsafe.ai/tokens.html

// Guest token: enough for /me and /estimate.
const guest = await call("POST", "/guest", { slug: "minimax-h3-prompt" });
// For a metered run use a personal token from
// https://minimax-h3-prompt.skillsafe.ai/tokens.html

// Guest token: enough for /me and /estimate.
guest, _ := call("POST", "/guest", map[string]string{"slug": "minimax-h3-prompt"})

// For a metered run use a personal token from
// https://minimax-h3-prompt.skillsafe.ai/tokens.html

// Guest token: enough for /me and /estimate.
String guest = Client.call("POST", "/guest", "{\"slug\":\"minimax-h3-prompt\"}");

// For a metered run use a personal token from
// https://minimax-h3-prompt.skillsafe.ai/tokens.html

# Guest token: enough for /me and /estimate.
guest = call("post", "/guest", { "slug" => "minimax-h3-prompt" })

# For a metered run use a personal token from
# https://minimax-h3-prompt.skillsafe.ai/tokens.html

<?php
// Guest token: enough for /me and /estimate.
$guest = call("POST", "/guest", ["slug" => "minimax-h3-prompt"]);

// For a metered run use a personal token from
// https://minimax-h3-prompt.skillsafe.ai/tokens.html

// Guest token: enough for /me and /estimate.
var guest = await Client.Call(HttpMethod.Post, "/guest", new { slug = "minimax-h3-prompt" });

// For a metered run use a personal token from
// https://minimax-h3-prompt.skillsafe.ai/tokens.html

curl -sS "https://api.skillsafe.ai/v1/app-api/me" -H "Authorization: Bearer $TOKEN"

# {"ok":true,"data":{"subject_type":"user","subject_id":"usr_...","credits":124500}}
# subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

me = call("GET", "/me")["data"]
print(me["subject_type"], me["credits"])
# subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

const me = await call("GET", "/me");
console.log(me.subject_type, me.credits);
// subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

me, _ := call("GET", "/me", nil)
fmt.Println(me["data"])
// subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

String me = Client.call("GET", "/me", null);
System.out.println(me);
// subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

me = call("get", "/me")["data"]
puts me["subject_type"], me["credits"]
# subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

<?php
$me = call("GET", "/me")["data"];
echo $me["subject_type"], " ", $me["credits"];
// subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

var me = await Client.Call(HttpMethod.Get, "/me");
Console.WriteLine(me.RootElement.GetProperty("data"));
// subject_type is "user" when signed in and "guest" otherwise. Guests cannot run.

curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/estimate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"task": "h3-prompt:build", "rules": "<the rules for this stage, from GET /h3rules.js>", "brief": "A woman at a workshop bench fits a brass hand to a clock face.", "mode": "I2VA", "seconds": 8, "refs": "Picture 1: the woman at the bench", "$model": "gpt-5.6-terra"}'

# Free, and it does not create a job. Returns hold_credits (a RESERVATION, not a
# price), min_credits, model, model_alias, markup_bps, and - when the app
# declares an input schema - input_checked plus warnings[] naming any unknown or
# mistyped field. Warnings are advisory: the run still happens and is charged.

est = call("POST", "/estimate", {
  "task": "h3-prompt:build",
  "rules": "<the rules for this stage, from GET /h3rules.js>",
  "brief": "A woman at a workshop bench fits a brass hand to a clock face.",
  "mode": "I2VA",
  "seconds": 8,
  "refs": "Picture 1: the woman at the bench",
  "$model": "gpt-5.6-terra"
})["data"]
print(est["hold_credits"], est["model"], est.get("warnings"))
# Free, and it creates no job. hold_credits is a RESERVATION, not a price.

const est = await call("POST", "/estimate", {
  "task": "h3-prompt:build",
  "rules": "<the rules for this stage, from GET /h3rules.js>",
  "brief": "A woman at a workshop bench fits a brass hand to a clock face.",
  "mode": "I2VA",
  "seconds": 8,
  "refs": "Picture 1: the woman at the bench",
  "$model": "gpt-5.6-terra"
});
console.log(est.hold_credits, est.model, est.warnings);
// Free, and it creates no job. hold_credits is a RESERVATION, not a price.

est, _ := call("POST", "/estimate", map[string]any{
    "task":   "h3-prompt:build",
    "rules":  rulesForTask,
    "brief":  "A woman at a workshop bench fits a brass hand to a clock face.",
    "mode":   "I2VA",
    "seconds": 8,
    "$model": "gpt-5.6-terra",
})
// Free, and it creates no job. hold_credits is a RESERVATION, not a price.

String est = Client.call("POST", "/estimate", """
{
  "task": "h3-prompt:build",
  "rules": "<the rules for this stage, from GET /h3rules.js>",
  "brief": "A woman at a workshop bench fits a brass hand to a clock face.",
  "mode": "I2VA",
  "seconds": 8,
  "refs": "Picture 1: the woman at the bench",
  "$model": "gpt-5.6-terra"
}""");
// Free, and it creates no job. hold_credits is a RESERVATION, not a price.

est = call("post", "/estimate", {
  "task"    => "h3-prompt:build",
  "rules"   => rules_for_task,
  "brief"   => "A woman at a workshop bench fits a brass hand to a clock face.",
  "mode"    => "I2VA",
  "seconds" => 8,
  "$model"  => "gpt-5.6-terra"
})["data"]
# Free, and it creates no job. hold_credits is a RESERVATION, not a price.

<?php
$est = call("POST", "/estimate", [
    "task"    => "h3-prompt:build",
    "rules"   => $rulesForTask,
    "brief"   => "A woman at a workshop bench fits a brass hand to a clock face.",
    "mode"    => "I2VA",
    "seconds" => 8,
    "$model"  => "gpt-5.6-terra",
])["data"];
// Free, and it creates no job. hold_credits is a RESERVATION, not a price.

var est = await Client.Call(HttpMethod.Post, "/estimate", new Dictionary<string, object> {
    ["task"]    = "h3-prompt:build",
    ["rules"]   = rulesForTask,
    ["brief"]   = "A woman at a workshop bench fits a brass hand to a clock face.",
    ["mode"]    = "I2VA",
    ["seconds"] = 8,
    ["$model"]  = "gpt-5.6-terra",
});
// Free, and it creates no job. hold_credits is a RESERVATION, not a price.

# Always send Idempotency-Key. Derive it from the task plus the input, so a
# retried request never double-bills and two tasks over one brief never collide.
JOB=$(curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: h3-h3promptbuild-9f2c1a" \
  -d '{"task": "h3-prompt:build", "rules": "<the rules for this stage, from GET /h3rules.js>", "brief": "A woman at a workshop bench fits a brass hand to a clock face.", "mode": "I2VA", "seconds": 8, "refs": "Picture 1: the woman at the bench", "$model": "gpt-5.6-terra"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["job_id"])')

# poll to a terminal state
curl -sS "https://api.skillsafe.ai/v1/app-api/jobs/$JOB" -H "Authorization: Bearer $TOKEN"

import time

started = call("POST", "/run", {
  "task": "h3-prompt:build",
  "rules": "<the rules for this stage, from GET /h3rules.js>",
  "brief": "A woman at a workshop bench fits a brass hand to a clock face.",
  "mode": "I2VA",
  "seconds": 8,
  "refs": "Picture 1: the woman at the bench",
  "$model": "gpt-5.6-terra"
},
               headers={"Idempotency-Key": "h3-h3promptbuild-9f2c1a"})["data"]

while True:
    job = call("GET", "/jobs/" + started["job_id"])["data"]
    if job["status"] in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(2)

print(job["output"]["output"])      # the Markdown package
print(job["charged_credits"])       # the ACTUAL cost, usually well under the hold

const started = await call("POST", "/run", {
  "task": "h3-prompt:build",
  "rules": "<the rules for this stage, from GET /h3rules.js>",
  "brief": "A woman at a workshop bench fits a brass hand to a clock face.",
  "mode": "I2VA",
  "seconds": 8,
  "refs": "Picture 1: the woman at the bench",
  "$model": "gpt-5.6-terra"
},
  { "Idempotency-Key": "h3-h3promptbuild-9f2c1a" });

let job;
do {
  await new Promise(r => setTimeout(r, 2000));
  job = await call("GET", `/jobs/${started.job_id}`);
} while (!["succeeded", "failed", "cancelled"].includes(job.status));

console.log(job.output.output);     // the Markdown package
console.log(job.charged_credits);   // the ACTUAL cost, usually well under the hold

started, _ := call("POST", "/run", body)   // + header Idempotency-Key
id := started["data"].(map[string]any)["job_id"].(string)

for {
    job, _ := call("GET", "/jobs/"+id, nil)
    st := job["data"].(map[string]any)["status"].(string)
    if st == "succeeded" || st == "failed" || st == "cancelled" {
        break
    }
    time.Sleep(2 * time.Second)
}

String started = Client.call("POST", "/run", body);   // + header Idempotency-Key
// then GET /jobs/{job_id} every two seconds until status is
// succeeded, failed or cancelled.

started = call("post", "/run", body)["data"]   # + header Idempotency-Key

loop do
  job = call("get", "/jobs/#{started['job_id']}")["data"]
  break if %%w[succeeded failed cancelled].include?(job["status"])
  sleep 2
end

<?php
$started = call("POST", "/run", $body)["data"];   // + header Idempotency-Key

do {
    sleep(2);
    $job = call("GET", "/jobs/" . $started["job_id"])["data"];
} while (!in_array($job["status"], ["succeeded", "failed", "cancelled"]));

echo $job["output"]["output"];

var started = await Client.Call(HttpMethod.Post, "/run", body);  // + Idempotency-Key
// then GET /jobs/{job_id} every two seconds until status is
// succeeded, failed or cancelled.

curl -sSN -X POST "https://api.skillsafe.ai/v1/app-api/run-stream" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: h3-h3promptbuild-9f2c1a" \
  -d '{"task": "h3-prompt:build", "rules": "<the rules for this stage, from GET /h3rules.js>", "brief": "A woman at a workshop bench fits a brass hand to a clock face.", "mode": "I2VA", "seconds": 8, "refs": "Picture 1: the woman at the bench", "$model": "gpt-5.6-terra"}'

# Server-sent events. `delta` frames carry {"text":"..."} - the incremental
# output. `job` frames carry the job object. `done` carries the terminal job.
# Accumulate the delta text: that is the package, arriving section by section.

req = urllib.request.Request(BASE + "/run-stream",
                             data=json.dumps(body).encode(), method="POST")
req.add_header("Authorization", "Bearer " + TOKEN)
req.add_header("Content-Type", "application/json")
req.add_header("Idempotency-Key", "h3-h3promptbuild-9f2c1a")

buf = ""
with urllib.request.urlopen(req) as r:
    for raw in r:
        line = raw.decode().strip()
        if not line.startswith("data:"):
            continue
        frame = json.loads(line[5:].strip())
        if "text" in frame:
            buf += frame["text"]
            # sections arrive in contract order; "## " marks each one starting

const res = await fetch(BASE + "/run-stream", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "h3-h3promptbuild-9f2c1a"
  },
  body: JSON.stringify(body)
});

const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = "";
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  for (const line of dec.decode(value).split("\n")) {
    if (!line.startsWith("data:")) continue;
    const frame = JSON.parse(line.slice(5).trim());
    if (frame.text) buf += frame.text;   // NOTE: the delta is frame.text
  }
}

// POST /run-stream with the same body and an Idempotency-Key header, then read
// the response body line by line. Lines beginning "data:" carry a JSON frame;
// frames with a "text" key are output deltas to accumulate.

// POST /run-stream with the same body and an Idempotency-Key header, then read
// the response as a line stream. Lines beginning "data:" carry a JSON frame;
// frames with a "text" key are output deltas to accumulate.

# POST /run-stream with the same body and an Idempotency-Key header, reading the
# response in chunks. Lines beginning "data:" carry a JSON frame; frames with a
# "text" key are output deltas to accumulate.

<?php
// POST /run-stream with the same body and an Idempotency-Key header, using
// CURLOPT_WRITEFUNCTION to read frames as they arrive. Lines beginning "data:"
// carry a JSON frame; frames with a "text" key are output deltas.

// POST /run-stream with the same body and an Idempotency-Key header, then read
// the response stream line by line. Lines beginning "data:" carry a JSON frame;
// frames with a "text" key are output deltas to accumulate.