Drive Flipbook Canvas from your own code

# The shortest path is the token page: it shows the token this browser already
# holds for the app and copies it as a shell export.
#   https://flipbook-canvas.skillsafe.ai/tokens.html
#
# Or mint a guest token from the command line. A guest can call /me and
# /estimate; the metered lanes need a personal token from signing in.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/guest \
  -H 'Content-Type: application/json' \
  -d '{"slug":"flipbook-canvas"}'
# -> {"data":{"token":"aut_...","guest_id":"gst_..."}}

export FLIPBOOK_TOKEN="aut_..."   # paste it, or use the token page's shell export

# Open https://flipbook-canvas.skillsafe.ai/tokens.html and press "Copy shell export",
# or mint a guest token:
import os, json, urllib.request

def guest():
    req = urllib.request.Request(
        "https://api.skillsafe.ai/v1/app-api/guest",
        data=json.dumps({"slug": "flipbook-canvas"}).encode(),
        headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req) as r:
        return json.load(r)["data"]["token"]

TOKEN = os.environ.get("FLIPBOOK_TOKEN") or guest()

// Open https://flipbook-canvas.skillsafe.ai/tokens.html and press "Copy token",
// or mint a guest token:
const API = "https://api.skillsafe.ai/v1/app-api";

async function guest() {
  const res = await fetch(`${API}/guest`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ slug: "flipbook-canvas" }),
  });
  const json = await res.json();
  return json.data.token;
}

let TOKEN = "YOUR_TOKEN";           // from the token page
if (TOKEN === "YOUR_TOKEN") TOKEN = await guest();

// Open https://flipbook-canvas.skillsafe.ai/tokens.html and press "Copy token",
// or mint a guest token.
package main

import (
    "bytes"; "encoding/json"; "net/http"; "os"
)

const API = "https://api.skillsafe.ai/v1/app-api"

func guest() (string, error) {
    body, _ := json.Marshal(map[string]string{"slug": "flipbook-canvas"})
    res, err := http.Post(API+"/guest", "application/json", bytes.NewReader(body))
    if err != nil { return "", err }
    defer res.Body.Close()
    var out struct { Data struct { Token string `json:"token"` } }
    json.NewDecoder(res.Body).Decode(&out)
    return out.Data.Token, nil
}

func token() string {
    if t := os.Getenv("FLIPBOOK_TOKEN"); t != "" { return t }
    t, _ := guest()
    return t
}

// Open https://flipbook-canvas.skillsafe.ai/tokens.html and press "Copy token",
// or mint a guest token.
import java.net.URI;
import java.net.http.*;

static final String API = "https://api.skillsafe.ai/v1/app-api";
static final HttpClient HTTP = HttpClient.newHttpClient();

static String guest() throws Exception {
    HttpRequest req = HttpRequest.newBuilder(URI.create(API + "/guest"))
        .header("Content-Type", "application/json")
        .POST(HttpRequest.BodyPublishers.ofString("{\"slug\":\"flipbook-canvas\"}"))
        .build();
    String body = HTTP.send(req, HttpResponse.BodyHandlers.ofString()).body();
    // any JSON library; the token is at data.token
    return body.split("\"token\":\"")[1].split("\"")[0];
}

static String TOKEN = System.getenv("FLIPBOOK_TOKEN");   // or paste "YOUR_TOKEN"

# Open https://flipbook-canvas.skillsafe.ai/tokens.html and press "Copy token",
# or mint a guest token.
require "net/http"
require "json"
require "uri"

API = "https://api.skillsafe.ai/v1/app-api"

def guest
  uri = URI("#{API}/guest")
  res = Net::HTTP.post(uri, { slug: "flipbook-canvas" }.to_json,
                       "Content-Type" => "application/json")
  JSON.parse(res.body)["data"]["token"]
end

TOKEN = ENV.fetch("FLIPBOOK_TOKEN") { guest }

<?php
// Open https://flipbook-canvas.skillsafe.ai/tokens.html and press "Copy token",
// or mint a guest token.
const API = "https://api.skillsafe.ai/v1/app-api";

function post_json(string $path, array $body, ?string $token = null): array {
    $headers = ["Content-Type: application/json"];
    if ($token) $headers[] = "Authorization: Bearer $token";
    $ctx = stream_context_create(["http" => [
        "method" => "POST",
        "header" => implode("\r\n", $headers),
        "content" => json_encode($body),
        "ignore_errors" => true,
    ]]);
    return json_decode(file_get_contents(API . $path, false, $ctx), true);
}

$guest = post_json("/guest", ["slug" => "flipbook-canvas"]);
$token = getenv("FLIPBOOK_TOKEN") ?: $guest["data"]["token"];

// Open https://flipbook-canvas.skillsafe.ai/tokens.html and press "Copy token",
// or mint a guest token.
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;

const string Api = "https://api.skillsafe.ai/v1/app-api";
var http = new HttpClient();

async Task<string> GuestAsync() {
    var res = await http.PostAsJsonAsync($"{Api}/guest", new { slug = "flipbook-canvas" });
    var doc = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
    return doc.RootElement.GetProperty("data").GetProperty("token").GetString()!;
}

var token = Environment.GetEnvironmentVariable("FLIPBOOK_TOKEN") ?? await GuestAsync();
http.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);

curl -s https://api.skillsafe.ai/v1/app-api/me -H "Authorization: Bearer $FLIPBOOK_TOKEN"
# -> {"data":{"subject_type":"user","credits":184200,"user_id":"usr_..."}}
#
# subject_type is "guest" until you sign in. Guests can price a run but not run it,
# unless the publisher has sponsorship switched on.

def get(path):
    req = urllib.request.Request(API + path,
                                 headers={"Authorization": "Bearer " + TOKEN})
    with urllib.request.urlopen(req) as r:
        return json.load(r)["data"]

me = get("/me")
print(me["subject_type"], me["credits"])

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

const me = await api("/me");
console.log(me.subject_type, me.credits);

func apiGet(path, token string) (map[string]any, error) {
    req, _ := http.NewRequest("GET", API+path, nil)
    req.Header.Set("Authorization", "Bearer "+token)
    res, err := http.DefaultClient.Do(req)
    if err != nil { return nil, err }
    defer res.Body.Close()
    var out struct{ Data map[string]any }
    json.NewDecoder(res.Body).Decode(&out)
    return out.Data, nil
}

me, _ := apiGet("/me", token())
fmt.Println(me["subject_type"], me["credits"])

HttpRequest me = HttpRequest.newBuilder(URI.create(API + "/me"))
    .header("Authorization", "Bearer " + TOKEN)
    .GET().build();
System.out.println(HTTP.send(me, HttpResponse.BodyHandlers.ofString()).body());

def api_get(path)
  uri = URI("#{API}#{path}")
  req = Net::HTTP::Get.new(uri)
  req["Authorization"] = "Bearer #{TOKEN}"
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  JSON.parse(res.body)["data"]
end

me = api_get("/me")
puts "#{me['subject_type']} #{me['credits']}"

<?php
function get_json(string $path, string $token): array {
    $ctx = stream_context_create(["http" => [
        "method" => "GET",
        "header" => "Authorization: Bearer $token",
        "ignore_errors" => true,
    ]]);
    return json_decode(file_get_contents(API . $path, false, $ctx), true);
}

$me = get_json("/me", $token)["data"];
echo $me["subject_type"], " ", $me["credits"], "\n";

var me = await http.GetFromJsonAsync<JsonDocument>($"{Api}/me");
var d = me!.RootElement.GetProperty("data");
Console.WriteLine($"{d.GetProperty("subject_type")} {d.GetProperty("credits")}");

# Free. No job, no charge. Price the exact body you intend to run - every lane
# has a different hold because the prompts and the output caps differ.
curl -s -X POST https://api.skillsafe.ai/v1/app-api/estimate \
  -H "Authorization: Bearer $FLIPBOOK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @plan-body.json
# -> {"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra","markup_bps":1000,
#             "hold_credits":3120,"min_credits":420,"sponsor_enabled":false}}

# The plate lane prices the image tier instead:
curl -s -X POST https://api.skillsafe.ai/v1/app-api/estimate \
  -H "Authorization: Bearer $FLIPBOOK_TOKEN" -H 'Content-Type: application/json' \
  -d '{"instruction":"...","$model":"gpt-image"}'
# -> hold_credits is priced per image, not per token

def post(path, body):
    req = urllib.request.Request(
        API + path, data=json.dumps(body).encode(),
        headers={"Content-Type": "application/json",
                 "Authorization": "Bearer " + TOKEN})
    with urllib.request.urlopen(req) as r:
        return json.load(r)["data"]

est = post("/estimate", plan_body)
print(est["model"], est["model_alias"], est["hold_credits"], est["min_credits"])
assert est["hold_credits"] <= me["credits"], "top up before running"

# The plate lane is priced separately, per image.
img = post("/estimate", {"instruction": "...", "$model": "gpt-image"})

const est = await api("/estimate", planBody);
console.log(est.model, est.model_alias, est.hold_credits, est.min_credits);
if (est.hold_credits > me.credits) throw new Error("not enough credits");

// The plate lane, priced per image:
const imgEst = await api("/estimate", { instruction: "...", $model: "gpt-image" });

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

est, _ := apiPost("/estimate", planBody, token())
fmt.Println(est["model"], est["hold_credits"])

String body = mapper.writeValueAsString(planBody);
HttpRequest est = HttpRequest.newBuilder(URI.create(API + "/estimate"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
System.out.println(HTTP.send(est, HttpResponse.BodyHandlers.ofString()).body());

def api_post(path, body)
  uri = URI("#{API}#{path}")
  req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json",
                                 "Authorization" => "Bearer #{TOKEN}")
  req.body = body.to_json
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  JSON.parse(res.body)["data"]
end

est = api_post("/estimate", plan_body)
puts "#{est['model']} holds #{est['hold_credits']}"

<?php
$est = post_json("/estimate", $planBody, $token)["data"];
printf("%s holds %d (min %d)\n",
       $est["model"], $est["hold_credits"], $est["min_credits"]);

var estRes = await http.PostAsJsonAsync($"{Api}/estimate", planBody);
var est = JsonDocument.Parse(await estRes.Content.ReadAsStringAsync())
    .RootElement.GetProperty("data");
Console.WriteLine($"{est.GetProperty("model")} holds {est.GetProperty("hold_credits")}");

# /run returns a job id immediately; poll /jobs/{id} until it is terminal.
# This is the lane to use for plates: an image run streams no deltas, so
# run-stream would buy you nothing.
#
# Send an Idempotency-Key on EVERY attempt. A retry that reuses the key returns
# the original job instead of billing a second one - including when the original
# FAILED, so salt the key per page load rather than deriving it only from input.
JOB=$(curl -s -X POST https://api.skillsafe.ai/v1/app-api/run \
  -H "Authorization: Bearer $FLIPBOOK_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: flipbook-canvas:render:p1abc:9f3a2:l7x8k:a1' \
  -d '{"instruction":"...","$model":"gpt-image"}' | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["job_id"])')

until curl -s https://api.skillsafe.ai/v1/app-api/jobs/$JOB -H "Authorization: Bearer $FLIPBOOK_TOKEN" \
      | grep -qE '"status":"(succeeded|failed)"'; do sleep 2; done

curl -s https://api.skillsafe.ai/v1/app-api/jobs/$JOB -H "Authorization: Bearer $FLIPBOOK_TOKEN" > job.json
# succeeded: data.output.images[0] = {"content_type":"image/png","b64":"..."}
# failed:    data.error is a plain STRING on this platform, not an object

import base64, time

job = post("/run", render_body)          # send an Idempotency-Key header in real code
job_id = job["job_id"]

while True:
    j = get(f"/jobs/{job_id}")
    if j["status"] in ("succeeded", "failed"):
        break
    time.sleep(2)

if j["status"] != "succeeded":
    err = j.get("error")
    raise SystemExit(err if isinstance(err, str) else err.get("message", "run failed"))

img = j["output"]["images"][0]
open("plate.png", "wb").write(base64.b64decode(img["b64"]))
print("charged", j.get("charged_credits"))

const started = await fetch(`${API}/run`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${TOKEN}`,
    "Idempotency-Key": `${"flipbook-canvas"}:render:${nodeId}:${hash}:${nonce}:a1`,
  },
  body: JSON.stringify(renderBody),
}).then((r) => r.json());

let job;
do {
  await new Promise((r) => setTimeout(r, 2000));
  job = await api(`/jobs/${started.data.job_id}`);
} while (job.status !== "succeeded" && job.status !== "failed");

if (job.status !== "succeeded") {
  // `error` arrives as a plain string here, not { message }
  throw new Error(typeof job.error === "string" ? job.error : job.error?.message);
}
const b64 = job.output.images[0].b64;

started, _ := apiPost("/run", renderBody, token())   // set Idempotency-Key too
jobID := started["job_id"].(string)

var job map[string]any
for {
    job, _ = apiGet("/jobs/"+jobID, token())
    s, _ := job["status"].(string)
    if s == "succeeded" || s == "failed" { break }
    time.Sleep(2 * time.Second)
}
if job["status"] != "succeeded" {
    log.Fatalf("run failed: %v", job["error"])   // a string, not an object
}

HttpRequest run = HttpRequest.newBuilder(URI.create(API + "/run"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "flipbook-canvas:render:p1abc:9f3a2:l7x8k:a1")
    .POST(HttpRequest.BodyPublishers.ofString(renderBody))
    .build();
String started = HTTP.send(run, HttpResponse.BodyHandlers.ofString()).body();
String jobId = started.split("\"job_id\":\"")[1].split("\"")[0];

String job;
do {
    Thread.sleep(2000);
    HttpRequest poll = HttpRequest.newBuilder(URI.create(API + "/jobs/" + jobId))
        .header("Authorization", "Bearer " + TOKEN).GET().build();
    job = HTTP.send(poll, HttpResponse.BodyHandlers.ofString()).body();
} while (!job.contains("\"succeeded\"") && !job.contains("\"failed\""));

started = api_post("/run", render_body)     # add an Idempotency-Key header
job_id = started["job_id"]

job = nil
loop do
  job = api_get("/jobs/#{job_id}")
  break if %w[succeeded failed].include?(job["status"])
  sleep 2
end

abort(job["error"].to_s) unless job["status"] == "succeeded"
File.binwrite("plate.png", Base64.decode64(job["output"]["images"][0]["b64"]))

<?php
$started = post_json("/run", $renderBody, $token)["data"];
$jobId = $started["job_id"];

do {
    sleep(2);
    $job = get_json("/jobs/$jobId", $token)["data"];
} while (!in_array($job["status"], ["succeeded", "failed"], true));

if ($job["status"] !== "succeeded") {
    // `error` is a plain string on this platform
    exit(is_string($job["error"]) ? $job["error"] : "run failed");
}
file_put_contents("plate.png", base64_decode($job["output"]["images"][0]["b64"]));

var req = new HttpRequestMessage(HttpMethod.Post, $"{Api}/run") {
    Content = JsonContent.Create(renderBody)
};
req.Headers.Add("Idempotency-Key", "flipbook-canvas:render:p1abc:9f3a2:l7x8k:a1");
var startedRes = await http.SendAsync(req);
var jobId = JsonDocument.Parse(await startedRes.Content.ReadAsStringAsync())
    .RootElement.GetProperty("data").GetProperty("job_id").GetString();

JsonElement job;
do {
    await Task.Delay(2000);
    var poll = await http.GetStringAsync($"{Api}/jobs/{jobId}");
    job = JsonDocument.Parse(poll).RootElement.GetProperty("data");
} while (job.GetProperty("status").GetString() is not ("succeeded" or "failed"));

# The text lanes stream. Each SSE frame is `event:` plus `data:`; the useful
# events are `delta` (a chunk of the JSON being written), `job`, `done` and
# `error`. `done.output.output` holds the whole reply.
curl -N -s -X POST https://api.skillsafe.ai/v1/app-api/run-stream \
  -H "Authorization: Bearer $FLIPBOOK_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: flipbook-canvas:plan:p1abc:9f3a2:l7x8k:a1' \
  -d @plan-body.json

# event: job
# data: {"job_id":"job_..."}
# event: delta
# data: {"text":"{\"lane\":\"plan\",\"title\":\"A dragon kiln"}
# ...
# event: done
# data: {"job_id":"job_...","status":"succeeded","charged_credits":812,
#         "truncated":false,"output":{"output":"{...the whole JSON object...}"}}

import urllib.request

req = urllib.request.Request(
    API + "/run-stream", data=json.dumps(plan_body).encode(),
    headers={"Content-Type": "application/json",
             "Authorization": "Bearer " + TOKEN,
             "Idempotency-Key": "flipbook-canvas:plan:p1abc:9f3a2:l7x8k:a1"})

raw, done = "", None
with urllib.request.urlopen(req) as r:
    event, data = "message", ""
    for line in r:
        line = line.decode().rstrip("\n")
        if line.startswith("event:"):
            event = line[6:].strip()
        elif line.startswith("data:"):
            data += line[5:].strip()
        elif line == "":
            if data:
                payload = json.loads(data)
                if event == "delta":
                    raw += payload.get("text", "")
                elif event in ("done", "pending"):
                    done = payload
                elif event == "error":
                    raise SystemExit(payload.get("message", "stream failed"))
            event, data = "message", ""

plan = json.loads((done or {}).get("output", {}).get("output") or raw)
print(plan["title"], len(plan["zones"]), "zones")

// In a browser the vendored SDK does this for you:
//   const done = await ss.runStream(input, { idempotencyKey, onDelta, onJob });
// Outside the browser, read the SSE stream directly:
const res = await fetch(`${API}/run-stream`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${TOKEN}`,
    "Idempotency-Key": `flipbook-canvas:plan:${nodeId}:${hash}:${nonce}:a1`,
  },
  body: JSON.stringify(planBody),
});

const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = "", raw = "", done = null;
for (;;) {
  const { value, done: end } = await reader.read();
  if (end) break;
  buf += dec.decode(value, { stream: true });
  let i;
  while ((i = buf.indexOf("\n\n")) >= 0) {
    const frame = buf.slice(0, i); buf = buf.slice(i + 2);
    let ev = "message", data = "";
    frame.split("\n").forEach((l) => {
      if (l.startsWith("event:")) ev = l.slice(6).trim();
      else if (l.startsWith("data:")) data += l.slice(5).trim();
    });
    if (!data) continue;
    const p = JSON.parse(data);
    if (ev === "delta") raw += p.text || "";
    else if (ev === "done" || ev === "pending") done = p;
    else if (ev === "error") throw new Error(p.message);
  }
}
const plan = JSON.parse(done?.output?.output || raw);

b, _ := json.Marshal(planBody)
req, _ := http.NewRequest("POST", API+"/run-stream", bytes.NewReader(b))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token())
req.Header.Set("Idempotency-Key", "flipbook-canvas:plan:p1abc:9f3a2:l7x8k:a1")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

sc := bufio.NewScanner(res.Body)
sc.Buffer(make([]byte, 1<<20), 1<<20)
var raw strings.Builder
event := "message"
for sc.Scan() {
    line := sc.Text()
    switch {
    case strings.HasPrefix(line, "event:"):
        event = strings.TrimSpace(line[6:])
    case strings.HasPrefix(line, "data:"):
        var p struct {
            Text   string `json:"text"`
            Output struct{ Output string `json:"output"` } `json:"output"`
        }
        json.Unmarshal([]byte(strings.TrimSpace(line[5:])), &p)
        if event == "delta" { raw.WriteString(p.Text) }
        if event == "done" && p.Output.Output != "" { raw.Reset(); raw.WriteString(p.Output.Output) }
    }
}
fmt.Println(raw.String())

HttpRequest stream = HttpRequest.newBuilder(URI.create(API + "/run-stream"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "application/json")
    .header("Idempotency-Key", "flipbook-canvas:plan:p1abc:9f3a2:l7x8k:a1")
    .POST(HttpRequest.BodyPublishers.ofString(planBody))
    .build();

StringBuilder raw = new StringBuilder();
HTTP.send(stream, HttpResponse.BodyHandlers.ofLines()).body().forEach(line -> {
    if (line.startsWith("data:")) {
        String data = line.substring(5).trim();
        // parse with any JSON library: delta frames carry .text,
        // the done frame carries .output.output
        if (data.contains("\"text\"")) raw.append(data);
    }
});
System.out.println(raw);

require "net/http"

uri = URI("#{API}/run-stream")
req = Net::HTTP::Post.new(uri,
  "Content-Type" => "application/json",
  "Authorization" => "Bearer #{TOKEN}",
  "Idempotency-Key" => "flipbook-canvas:plan:p1abc:9f3a2:l7x8k:a1")
req.body = plan_body.to_json

raw = ""
done = nil
event = "message"
Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(req) do |res|
    res.read_body do |chunk|
      chunk.each_line do |line|
        line = line.chomp
        if line.start_with?("event:") then event = line[6..].strip
        elsif line.start_with?("data:")
          p = JSON.parse(line[5..].strip) rescue next
          raw << (p["text"] || "") if event == "delta"
          done = p if event == "done"
        end
      end
    end
  end
end

plan = JSON.parse(done&.dig("output", "output") || raw)

<?php
// SSE over a plain stream: read line by line and reassemble the frames.
$ctx = stream_context_create(["http" => [
    "method" => "POST",
    "header" => implode("\r\n", [
        "Content-Type: application/json",
        "Authorization: Bearer $token",
        "Idempotency-Key: flipbook-canvas:plan:p1abc:9f3a2:l7x8k:a1",
    ]),
    "content" => json_encode($planBody),
]]);

$fh = fopen(API . "/run-stream", "r", false, $ctx);
$raw = ""; $done = null; $event = "message";
while (($line = fgets($fh)) !== false) {
    $line = rtrim($line, "\r\n");
    if (str_starts_with($line, "event:")) { $event = trim(substr($line, 6)); continue; }
    if (!str_starts_with($line, "data:")) continue;
    $p = json_decode(trim(substr($line, 5)), true);
    if ($event === "delta") $raw .= $p["text"] ?? "";
    if ($event === "done") $done = $p;
}
fclose($fh);
$plan = json_decode($done["output"]["output"] ?? $raw, true);

var streamReq = new HttpRequestMessage(HttpMethod.Post, $"{Api}/run-stream") {
    Content = JsonContent.Create(planBody)
};
streamReq.Headers.Add("Idempotency-Key", "flipbook-canvas:plan:p1abc:9f3a2:l7x8k:a1");

using var res = await http.SendAsync(streamReq, HttpCompletionOption.ResponseHeadersRead);
using var reader = new StreamReader(await res.Content.ReadAsStreamAsync());

var raw = new StringBuilder();
string ev = "message";
while (await reader.ReadLineAsync() is string line) {
    if (line.StartsWith("event:")) { ev = line[6..].Trim(); continue; }
    if (!line.StartsWith("data:")) continue;
    var p = JsonDocument.Parse(line[5..].Trim()).RootElement;
    if (ev == "delta" && p.TryGetProperty("text", out var t)) raw.Append(t.GetString());
    if (ev == "done" && p.TryGetProperty("output", out var o))
        raw.Clear().Append(o.GetProperty("output").GetString());
}
Console.WriteLine(raw.ToString());

# The two vision lanes need an image on the platform first. Upload it, then pass
# its id as $files. `annotate` sends the plate; `pick` sends the plate with a red
# circled crosshair drawn at the press point.
FILE=$(curl -s -X POST https://api.skillsafe.ai/v1/app-api/files \
  -H "Authorization: Bearer $FLIPBOOK_TOKEN" \
  -F 'file=@plate.jpg' -F 'name=plate.jpg' \
  | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["file"]["file_id"])')

# then include it in the run body
jq --arg f "$FILE" '. + {"$files": [$f]}' annotate-body.json > body.json
curl -s -X POST https://api.skillsafe.ai/v1/app-api/run-stream \
  -H "Authorization: Bearer $FLIPBOOK_TOKEN" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: flipbook-canvas:annotate:p1abc:aa11:l7x8k:a1" -d @body.json

# A short-lived signed URL for display (works directly in <img src>):
curl -s https://api.skillsafe.ai/v1/app-api/files/$FILE/url -H "Authorization: Bearer $FLIPBOOK_TOKEN"

import mimetypes, uuid

def upload(path):
    boundary = "----flip" + uuid.uuid4().hex
    name = os.path.basename(path)
    mime = mimetypes.guess_type(name)[0] or "application/octet-stream"
    body = b"".join([
        f"--{boundary}\r\n".encode(),
        f'Content-Disposition: form-data; name="file"; filename="{name}"\r\n'.encode(),
        f"Content-Type: {mime}\r\n\r\n".encode(),
        open(path, "rb").read(), b"\r\n",
        f"--{boundary}--\r\n".encode(),
    ])
    req = urllib.request.Request(
        API + "/files", data=body,
        headers={"Content-Type": f"multipart/form-data; boundary={boundary}",
                 "Authorization": "Bearer " + TOKEN})
    with urllib.request.urlopen(req) as r:
        return json.load(r)["data"]["file"]["file_id"]

annotate_body["$files"] = [upload("plate.jpg")]

// In the browser, the SDK wraps this:
//   const f = await ss.files.upload(new File([blob], "plate.jpg", { type: "image/jpeg" }));
//   img.src = await ss.files.url(f.file_id);
const fd = new FormData();
fd.append("file", blob, "plate.jpg");
fd.append("name", "plate.jpg");

const up = await fetch(`${API}/files`, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}` },   // no Content-Type: FormData sets it
  body: fd,
}).then((r) => r.json());

annotateBody.$files = [up.data.file.file_id];

var buf bytes.Buffer
w := multipart.NewWriter(&buf)
part, _ := w.CreateFormFile("file", "plate.jpg")
f, _ := os.Open("plate.jpg")
io.Copy(part, f)
w.WriteField("name", "plate.jpg")
w.Close()

req, _ := http.NewRequest("POST", API+"/files", &buf)
req.Header.Set("Content-Type", w.FormDataContentType())
req.Header.Set("Authorization", "Bearer "+token())
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

var out struct {
    Data struct{ File struct{ FileID string `json:"file_id"` } } `json:"data"`
}
json.NewDecoder(res.Body).Decode(&out)
annotateBody["$files"] = []string{out.Data.File.FileID}

// java.net.http has no multipart builder; assemble the body yourself.
String boundary = "----flip" + System.nanoTime();
byte[] image = Files.readAllBytes(Path.of("plate.jpg"));
var out = new ByteArrayOutputStream();
out.writeBytes(("--" + boundary + "\r\n").getBytes());
out.writeBytes(("Content-Disposition: form-data; name=\"file\"; filename=\"plate.jpg\"\r\n").getBytes());
out.writeBytes("Content-Type: image/jpeg\r\n\r\n".getBytes());
out.writeBytes(image);
out.writeBytes(("\r\n--" + boundary + "--\r\n").getBytes());

HttpRequest up = HttpRequest.newBuilder(URI.create(API + "/files"))
    .header("Authorization", "Bearer " + TOKEN)
    .header("Content-Type", "multipart/form-data; boundary=" + boundary)
    .POST(HttpRequest.BodyPublishers.ofByteArray(out.toByteArray()))
    .build();
String uploaded = HTTP.send(up, HttpResponse.BodyHandlers.ofString()).body();

require "net/http/post/multipart"   # gem: multipart-post

uri = URI("#{API}/files")
File.open("plate.jpg") do |f|
  req = Net::HTTP::Post::Multipart.new(uri.path,
    "file" => UploadIO.new(f, "image/jpeg", "plate.jpg"),
    "name" => "plate.jpg")
  req["Authorization"] = "Bearer #{TOKEN}"
  res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
  file_id = JSON.parse(res.body)["data"]["file"]["file_id"]
  annotate_body["$files"] = [file_id]
end

<?php
$ch = curl_init(API . "/files");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
    CURLOPT_POSTFIELDS => [
        "file" => new CURLFile("plate.jpg", "image/jpeg", "plate.jpg"),
        "name" => "plate.jpg",
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$uploaded = json_decode(curl_exec($ch), true);
curl_close($ch);

$annotateBody['$files'] = [$uploaded["data"]["file"]["file_id"]];

using var form = new MultipartFormDataContent();
var bytes = await File.ReadAllBytesAsync("plate.jpg");
var part = new ByteArrayContent(bytes);
part.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg");
form.Add(part, "file", "plate.jpg");
form.Add(new StringContent("plate.jpg"), "name");

var upRes = await http.PostAsync($"{Api}/files", form);
var fileId = JsonDocument.Parse(await upRes.Content.ReadAsStringAsync())
    .RootElement.GetProperty("data").GetProperty("file")
    .GetProperty("file_id").GetString();