StoryMint API Docs

X-API-Key: sm_your_key_here

Authorization: Bearer <firebase_id_token>

https://felice-uninterrupted-vicente.ngrok-free.dev

# Create a branded series of books
for topic in ["Space", "Ocean", "Jungle"]:
    resp = requests.post(f"{BASE}/api/generate",
        headers={"X-API-Key": API_KEY},
        json={
            "prompt": f"A child explores the {topic.lower()}",
            "author": "Your Publishing Company",
            "series": f"Little Explorers: {topic}",
            "art_style": "watercolor",
            "book_format": "picture",
        })
    print(f"Started {topic}: {resp.json()['job_id']}")

import requests, time

API_KEY = "sm_your_key_here"
BASE    = "https://felice-uninterrupted-vicente.ngrok-free.dev"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

# 1. Generate
gen = requests.post(f"{BASE}/api/generate", headers=HEADERS, json={
    "prompt": "A cat astronaut discovers a candy planet",
    "book_format": "comic",
    "author": "Starlight Studios",
    "art_style": "cartoon",
    "num_pages": 30,
}).json()
job_id = gen["job_id"]
print(f"Job: {job_id}")

# 2. Poll until done
while True:
    status = requests.get(f"{BASE}/api/status/{job_id}",
                          headers=HEADERS).json()
    print(f"  [{status.get('pct', 0):3d}%] {status.get('msg', '')}")
    if status["status"] in ("done", "error"):
        break
    time.sleep(3)

if status["status"] == "error":
    print("Generation failed:", status.get("msg"))
    exit(1)

# 3. Get book data
book = requests.get(f"{BASE}/api/book/{job_id}",
                    headers=HEADERS).json()
print(f"\nTitle: {book['title']}")
print(f"Pages: {len(book.get('pages', []))}")

# 4. AI edit
edit = requests.post(f"{BASE}/api/book/{job_id}/chat",
    headers=HEADERS,
    json={"message": "Add more humor to page 3"}).json()
print(f"Edit: {edit.get('assistant_message')}")

# 5. Download ZIP
dl = requests.get(f"{BASE}/api/download/{job_id}",
                  headers=HEADERS)
if dl.status_code == 200:
    with open(f"{book['title']}.zip", "wb") as f:
        f.write(dl.content)
    print("Downloaded!")
else:
    print("Download error:", dl.json())

const API_KEY = "sm_your_key_here";
const BASE    = "https://felice-uninterrupted-vicente.ngrok-free.dev";
const headers = {
  "Content-Type": "application/json",
  "X-API-Key": API_KEY,
};

// 1. Generate
const genResp = await fetch(`${BASE}/api/generate`, {
  method: "POST", headers,
  body: JSON.stringify({
    prompt: "A cat astronaut discovers a candy planet",
    book_format: "comic",
    author: "Starlight Studios",
    art_style: "cartoon",
    num_pages: 30,
  }),
});
const { job_id } = await genResp.json();
console.log("Job:", job_id);

// 2. Poll
let status;
do {
  await new Promise(r => setTimeout(r, 3000));
  const r = await fetch(`${BASE}/api/status/${job_id}`, { headers });
  status = await r.json();
  console.log(`  [${status.pct x 0}%] ${status.msg x ""}`);
} while (status.status === "running");

// 3. Get book
const book = await (await fetch(`${BASE}/api/book/${job_id}`,
  { headers })).json();
console.log("Title:", book.title);

// 4. Chat edit
const edit = await (await fetch(`${BASE}/api/book/${job_id}/chat`, {
  method: "POST", headers,
  body: JSON.stringify({ message: "Make the ending funnier" }),
})).json();
console.log("Edit:", edit.assistant_message);

// 5. Download (Node.js)
const dlResp = await fetch(`${BASE}/api/download/${job_id}`,
  { headers });
if (dlResp.ok) {
  const fs = await import("fs");
  const buf = Buffer.from(await dlResp.arrayBuffer());
  fs.writeFileSync(`${book.title}.zip`, buf);
  console.log("Downloaded!");
}

// 5b. Download (Browser)
// const blob = await dlResp.blob();
// const a = document.createElement("a");
// a.href = URL.createObjectURL(blob);
// a.download = `${book.title}.zip`;
// a.click();

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

public class StoryMintExample {
    static final String API_KEY = "sm_your_key_here";
    static final String BASE = "https://felice-uninterrupted-vicente.ngrok-free.dev";
    static final HttpClient client = HttpClient.newHttpClient();

    static HttpRequest.Builder req(String path) {
        return HttpRequest.newBuilder()
            .uri(URI.create(BASE + path))
            .header("X-API-Key", API_KEY)
            .header("Content-Type", "application/json");
    }

    public static void main(String[] args) throws Exception {
        // 1. Generate
        String body = """
            {
              "prompt": "A cat astronaut discovers a candy planet",
              "book_format": "comic",
              "author": "Starlight Studios",
              "art_style": "cartoon",
              "num_pages": 30
            }""";
        var genResp = client.send(
            req("/api/generate").POST(
                HttpRequest.BodyPublishers.ofString(body)).build(),
            HttpResponse.BodyHandlers.ofString());
        System.out.println("Generate: " + genResp.body());
        // Parse job_id from JSON response

        String jobId = "PARSE_FROM_RESPONSE";

        // 2. Poll status
        while (true) {
            var statusResp = client.send(
                req("/api/status/" + jobId).GET().build(),
                HttpResponse.BodyHandlers.ofString());
            System.out.println("Status: " + statusResp.body());
            if (statusResp.body().contains("\"done\"") ||
                statusResp.body().contains("\"error\"")) break;
            Thread.sleep(3000);
        }

        // 3. Download
        var dlResp = client.send(
            req("/api/download/" + jobId).GET().build(),
            HttpResponse.BodyHandlers.ofByteArray());
        if (dlResp.statusCode() == 200) {
            Files.write(Path.of("book.zip"), dlResp.body());
            System.out.println("Downloaded!");
        }
    }
}

# 1. Generate a book
JOB=$(curl -s -X POST \
  https://felice-uninterrupted-vicente.ngrok-free.dev/api/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sm_your_key_here" \
  -d '{
    "prompt": "A cat astronaut discovers a candy planet",
    "book_format": "comic",
    "author": "Starlight Studios",
    "art_style": "cartoon",
    "num_pages": 30
  }')
echo "Generate response: $JOB"
JOB_ID=$(echo $JOB | grep -o '"job_id":"[^"]*"' | cut -d'"' -f4)

# 2. Poll status until done
while true; do
  STATUS=$(curl -s \
    https://felice-uninterrupted-vicente.ngrok-free.dev/api/status/$JOB_ID \
    -H "X-API-Key: sm_your_key_here")
  echo "Status: $STATUS"
  echo "$STATUS" | grep -q '"done"\|"error"' && break
  sleep 3
done

# 3. Get book data
curl -s \
  https://felice-uninterrupted-vicente.ngrok-free.dev/api/book/$JOB_ID \
  -H "X-API-Key: sm_your_key_here" | python3 -m json.tool

# 4. Download ZIP
curl -o book.zip \
  https://felice-uninterrupted-vicente.ngrok-free.dev/api/download/$JOB_ID \
  -H "X-API-Key: sm_your_key_here"

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

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "sm_your_key_here");
var baseUrl = "https://felice-uninterrupted-vicente.ngrok-free.dev";

// 1. Generate
var genPayload = JsonSerializer.Serialize(new {
    prompt = "A cat astronaut discovers a candy planet",
    book_format = "comic",
    author = "Starlight Studios",
    art_style = "cartoon",
    num_pages = 30,
});
var genResp = await client.PostAsync($"{baseUrl}/api/generate",
    new StringContent(genPayload, Encoding.UTF8, "application/json"));
var genJson = JsonDocument.Parse(await genResp.Content.ReadAsStringAsync());
var jobId = genJson.RootElement.GetProperty("job_id").GetString();
Console.WriteLine($"Job: {jobId}");

// 2. Poll
while (true) {
    var statusResp = await client.GetStringAsync($"{baseUrl}/api/status/{jobId}");
    Console.WriteLine($"Status: {statusResp}");
    if (statusResp.Contains("\"done\"") || statusResp.Contains("\"error\"")) break;
    await Task.Delay(3000);
}

// 3. Download
var dlResp = await client.GetAsync($"{baseUrl}/api/download/{jobId}");
if (dlResp.IsSuccessStatusCode) {
    var bytes = await dlResp.Content.ReadAsByteArrayAsync();
    await File.WriteAllBytesAsync("book.zip", bytes);
    Console.WriteLine("Downloaded!");
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

const apiKey = "sm_your_key_here"
const base = "https://felice-uninterrupted-vicente.ngrok-free.dev"

func apiReq(method, path string, body interface{}) (*http.Response, error) {
    var buf io.Reader
    if body != nil {
        b, _ := json.Marshal(body)
        buf = bytes.NewBuffer(b)
    }
    req, _ := http.NewRequest(method, base+path, buf)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)
    return http.DefaultClient.Do(req)
}

func main() {
    // 1. Generate
    resp, _ := apiReq("POST", "/api/generate", map[string]interface{}{
        "prompt":      "A cat astronaut discovers a candy planet",
        "book_format": "comic",
        "author":      "Starlight Studios",
        "art_style":   "cartoon",
        "num_pages":   30,
    })
    var gen map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&gen)
    resp.Body.Close()
    jobID := gen["job_id"].(string)
    fmt.Println("Job:", jobID)

    // 2. Poll
    for {
        resp, _ := apiReq("GET", "/api/status/"+jobID, nil)
        var st map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&st)
        resp.Body.Close()
        fmt.Printf("  [%.0f%%] %s\n", st["pct"], st["msg"])
        if st["status"] == "done" || st["status"] == "error" {
            break
        }
        time.Sleep(3 * time.Second)
    }

    // 3. Download
    resp, _ = apiReq("GET", "/api/download/"+jobID, nil)
    defer resp.Body.Close()
    if resp.StatusCode == 200 {
        f, _ := os.Create("book.zip")
        io.Copy(f, resp.Body)
        f.Close()
        fmt.Println("Downloaded!")
    }
}

{
  "error": "Descriptive error message here",
  "detail": "Additional context (optional)"
}

resp = requests.post(f"{BASE}/api/generate",
    headers=HEADERS, json=payload)

if resp.status_code == 200:
    job_id = resp.json()["job_id"]
elif resp.status_code == 403:
    print("Quota exceeded:", resp.json().get("error"))
elif resp.status_code == 401:
    print("Invalid API key. Check your X-API-Key header.")
else:
    print(f"Error {resp.status_code}:", resp.json())