Images

Generate and edit images, billed per image.

Generate an image

POST/api/v1/images/generationsPer image

Send a prompt and get images back. Attach a reference image and the model edits it instead. The request follows OpenAI's images API, so the OpenAI SDK works.

Request body

modelstringrequiredAn image model id from the media menu, or clawhunter/smart to let Smart Router pick.
promptstringWhat to make. With a reference image, what to change. Required unless you send builder.
stylestringA style id from the styles list. It adds that look to your prompt.
builderobjectCharacter builder picks from the builder list. Each key is a section id, and each value is an option id or a list of them. Add "random": true to have the rest drawn for you. Not with style.
nintegerHow many images. Defaults to 1, up to 10.
image_urlstringOne reference image to edit, as an https URL or a data URL.
input_imagesstring[]Several reference images. The first is the one edited. The model's max_references on the menu says how many it takes.
aspect_ratiostringThe shape, on models that list aspect ratios. It doesn't change the price.
qualitystringThe quality tier, on models that list one. On clawhunter/smart it picks the routing tier instead, and defaults to medium.low · medium · high
resolutionstringThe resolution tier, on models that list one. Not on clawhunter/smart.1K · 2K · 4K
sizestringAccepted for OpenAI compatibility. Most models render their own size, so use aspect_ratio.
savebooleanCalls with a key also save what they make to your My Media, under the API filter. Send false to skip that.

Example request

import OpenAI from "openai";​const client = new OpenAI({  apiKey: process.env.CLAWHUNTER_API_KEY,  baseURL: "https://mystudios.fun/api/v1",});​const image = await client.images.generate({  model: "clawhunter/smart",  prompt: "A lighthouse on a sea cliff at golden hour",});

Response

OpenAI's images response with a billing block added. Each entry in data is b64_json or a url, depending on the model.

Response
{  "created": 1790000000,  "data": [{ "b64_json": "iVBORw0KGgo…" }],  "billing": {    "model": "gpt-image-2-6-flare",    "operation": "generate",    "requested_model": "clawhunter/smart",    "images": 1,    "usd": 0.024,    "usage_usd": 0.024,    "quote_usd": 0.0342,    "note": "routed to GPT Image 2.6 Flare"  }}

Styles and the character builder

  • A style adds a look to your prompt. Describe the subject and let the style handle the rest.
  • Builder picks write the whole prompt for you, so any prompt you send is ignored.
  • A build is a character sheet of one character, seen from several angles.
  • Sections you leave out are up to the model. An unknown id returns 400.
  • Add "random": trueand every section you leave out is drawn the way Studio's Randomize does it. The sections you send stay, so animal and female make a random female animal.
  • With random, the character type is Average unless you send one. "builder": "random" on its own is a random person.
  • Attach a reference image and a style restyles it, or a build starts from that person.
  • Both bill like any other call, at the model and settings you pick.
  • A builder response includes the picks it ran. Send them back to build from the same prompt again.
  • A style or builder call returns each image as url, the full-quality file, and preview_url, a lighter copy for display. Both links expire.

The settings below are the ones Studio uses for a build.

const res = await fetch("https://mystudios.fun/api/v1/images/generations", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.CLAWHUNTER_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    model: "gpt-image-2-6-flare",    aspect_ratio: "16:9",    quality: "high",    resolution: "2K",    builder: { "gender": "female", "hairstyle": "mullet", "hair-color": "platinum", "style": "streetstyle" },  }),});

Billing and limits

  • Billed per image at the model's price, listed on Models.
  • A quality or resolution tier above the default scales the price by the multiplier on the menu.
  • The call reserves the price per image times n. With credits, you pay for the images produced.
  • With x402, you pay that reserve as the price.
  • An option the model doesn't list returns 400.
  • clawhunter/smart needs an API key.
  • Calls with a key pay from credits; the free images are the web app's.
  • A 4K or high-quality image can take a few minutes.
  • A rejected or failed request is not charged.

Make a character

POST/api/v1/images/charactersPer render

Get a character sheet, a square headshot, and a 9:16 full body that all show the same character. Describe them with builder picks, a random roll, a prompt, an image, or a mix. The headshot works as an avatar or a token logo.

Request body

shotsstring[]Which shots you want. Defaults to sheet.sheet · headshot · full_body
picksobjectTraits from the builder list. Send "species": "animal" for an animal, also when it comes from an image.
randombooleanDraws every trait you leave out, the way Studio's Randomize does.
promptstringA description, like "a chaotic gaming streamer".
image_urlstringAn image of the character, as an https URL or a data URL.
image_kindstringWhat your image shows. Defaults to photo.photo · headshot · full_body · sheet
stylestringAn art style from the styles list (type style), for the headshot and full body.
modelstringDefaults to gpt-image-2-6-flare. Any image model that edits and renders all three shapes.
qualitystringDefaults to high.low · medium · high
resolutionstringDefaults to 2K.
savebooleanThe shots also save to your My Media, under the API filter. Send false to skip that.

Example request

const res = await fetch("https://mystudios.fun/api/v1/images/characters", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.CLAWHUNTER_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({  "random": true,  "picks": { "species": "animal", "animal": "fox" },  "shots": ["sheet", "headshot", "full_body"],  "style": "pixel-art"}),});const { shots } = await res.json();

Response

Each shot is b64_json or a url, depending on the model. When you send picks or random, builder holds the traits that ran. Send them back as picks to build the same character again.

Response
{  "shots": {    "sheet": { "b64_json": "iVBORw0KGgo…" },    "headshot": { "b64_json": "iVBORw0KGgo…" },    "full_body": { "b64_json": "iVBORw0KGgo…" }  },  "builder": { "picks": { "species": ["animal"], "type": ["average"], "animal": ["fox"], "gender": ["male"], "hairstyle": ["buzz-cut"], "style": ["western"], "outfit": ["western-8"] }, "version": 16 },  "billing": { "model": "gpt-image-2-6-flare", "renders": 3, "usd": 0.17, "usage_usd": 0.17, "quote_usd": 0.17, "note": "settled per render" }}

How shots match

  • Ask for more than one shot and we make the sheet first, then the others from it.
  • The sheet comes back too, since you pay for it.
  • Send a sheet as your image and it's used as is, with no new sheet.
  • A single headshot from an image is one render.
  • A full body from a headshot or a photo invents the body to fit.
  • A style applies to the headshot and full body. The sheet stays realistic so the shots keep every detail.

Billing and limits

  • Billed per render at the model's price, from prepaid credits. It needs an API key and takes no x402 payment.
  • If the sheet fails, nothing is charged. If a later shot fails, it's listed in errors and isn't charged.
  • Three shots usually take under a minute.
  • The shots save to your My Media, under the API filter. Send save: false to skip that.

List preset characters

GET/api/v1/images/characters/presetsFree

Studio's ready-made characters, people and animals, each with its traits, a still, and its character sheet. Send a sheet_url as image_url with image_kind set to sheet to get a headshot or full body of that character without making a new sheet.

List styles

GET/api/v1/images/stylesFree

Every style and template you can send as style, each with an id, a name, a one-line description, and an example_image thumbnail for your own picker. The image is for display only, so always send the id. Add ?search= to filter by words, for example ?search=mascot.

List builder traits

GET/api/v1/images/builderFree

The builder's sections, such as gender, hairstyle, and eye color, with the option ids each one takes. Multi sections take several picks. The rest keep the first. Picture options include an example_image thumbnail and color options a hexvalue, so you can show them in your own picker. They're for display only. Always send the option id.