{"openapi":"3.1.0","info":{"title":"Higgsfield API (Bowmark)","version":"e833508f87ff","description":"Higgsfield's own documented generation API — turns a text prompt (or a prompt plus an input image) into images or video across 25 models live on this account, including Kling 2.5 Turbo, MiniMax Hailuo 02/2.3, WAN 2.5 and Higgsfield's own Soul and DoP. Every call is quoted by Higgsfield before it is submitted, and only a generation watched to completion is charged.\n\nEvery function Bowmark has for Higgsfield (higgsfield.ai) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/higgsfield/listModels":{"post":{"operationId":"listModels","summary":"Lists every generation model Bowmark's Higgsfield account can actually call, with what each one produces, whether it needs an input image, and what one call was measured to cost.","description":"Lists every generation model Bowmark's Higgsfield account can actually call, with what each one produces, whether it needs an input image, and what one call was measured to cost. Measured against the live API on 2026-09-16 by estimating all 48 endpoints Higgsfield's OpenAPI document publishes: 25 answered, and the rest refused as model_not_found, model_blocked or model_disabled — so this is the callable set, not the documented one. Takes no arguments and makes no request.\n\nCalls `bowmark.providers.higgsfield.listModels`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<higgsfieldModel[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/higgsfield/estimateCost":{"post":{"operationId":"estimateCost","summary":"Asks Higgsfield what one generation will cost, for exactly the parameters you would submit, before submitting it — the vendor's own credit and US-dollar figure for this account, with any discount alre","description":"Asks Higgsfield what one generation will cost, for exactly the parameters you would submit, before submitting it — the vendor's own credit and US-dollar figure for this account, with any discount already applied. Generates nothing, produces no media and costs nothing. `model` defaults to `soul`. This is the same quote the generate functions take internally and charge from, so it is the honest answer to \"what am I about to spend\".\n\nCalls `bowmark.providers.higgsfield.estimateCost`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<higgsfieldEstimate>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"prompt":{"type":"string"},"model":{"type":"string"}},"required":["prompt"],"additionalProperties":{},"description":"TypeScript: `{ prompt: string; model?: string; [param: string]: unknown }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/higgsfield/generateImage":{"post":{"operationId":"generateImage","summary":"Generates one or more images from a text prompt and waits for them, returning the finished image URLs together with what Higgsfield quoted.","description":"Generates one or more images from a text prompt and waits for them, returning the finished image URLs together with what Higgsfield quoted. `model` defaults to `soul` ($0.094 measured); `listModels()` has the rest. Any other key — `aspect_ratio`, `num_images`, `input_images`, `output_format` — is passed to Higgsfield untouched, since each model takes its own. Waits up to `waitMs` for a terminal state, counted from the start of the call (default and maximum 60000, so the whole call returns inside a run). A wait always happens — a submit that never watches its own result is a generation Higgsfield bills us for and nobody is charged for — so the floor is 20000. **The finished images are copied into your Bowmark account automatically and come back on `files` — use those URLs, not `imageUrls`.** Higgsfield deletes its own copy after about seven days; a file in your account is yours until you delete it, and costs storage while you keep it. Pass `save: false` to skip the copy and take the expiring links. Which key serves the call, and who is charged, is in this provider's key note above; your own goes in the `x-bowmark-vendor-key-higgsfield` header.\n\nCalls `bowmark.providers.higgsfield.generateImage`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<higgsfieldGeneration>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"anyOf":[{"type":"string"},{"type":"object","properties":{"prompt":{"type":"string"},"model":{"type":"string"},"waitMs":{"type":"number"},"save":{"type":"boolean"}},"required":["prompt"],"additionalProperties":{}}],"description":"TypeScript: `string | { prompt: string; model?: string; waitMs?: number; save?: boolean; [param: string]: unknown }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/higgsfield/generateVideo":{"post":{"operationId":"generateVideo","summary":"Generates a video from a text prompt — or from a prompt plus an input image on the image-to-video models — and waits for it, returning the finished video URL together with what Higgsfield quoted.","description":"Generates a video from a text prompt — or from a prompt plus an input image on the image-to-video models — and waits for it, returning the finished video URL together with what Higgsfield quoted. `model` defaults to `hailuo-02-standard` ($0.090 measured, the cheapest live video model); Kling 2.1 Master is $1.400, so check `listModels()` or `estimateCost` before reaching for a big one. Any other key (`duration`, `resolution`, `input_images`) is passed to Higgsfield untouched. Waits up to `waitMs`, counted from the start of the call (default and maximum 60000, so the whole call returns inside a run). Video usually renders past that, which is normal: you get `settled: false` and the handle, and collect it with `getRequestStatus`. **A call that waits copies the finished video into your Bowmark account and returns it on `files` — use that URL, not `videoUrl`**, because Higgsfield deletes its own copy after about seven days. Pass `save: false` to skip the copy. A call whose wait runs out saves nothing, since nothing has rendered yet — collect and download it yourself.\n\nCalls `bowmark.providers.higgsfield.generateVideo`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<higgsfieldGeneration>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"anyOf":[{"type":"string"},{"type":"object","properties":{"prompt":{"type":"string"},"model":{"type":"string"},"waitMs":{"type":"number"},"save":{"type":"boolean"}},"required":["prompt"],"additionalProperties":{}}],"description":"TypeScript: `string | { prompt: string; model?: string; waitMs?: number; save?: boolean; [param: string]: unknown }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/higgsfield/getRequestStatus":{"post":{"operationId":"getRequestStatus","summary":"Checks one submitted generation by its `requestId` and returns its current state plus any finished media.","description":"Checks one submitted generation by its `requestId` and returns its current state plus any finished media. Use it after a generate call that returned `settled: false`, which means the wait ran out while the generation was still running. `status` is Higgsfield's own: `queued`, `in_progress`, `completed`, `failed`, `nsfw` (refused by moderation — reword the prompt) or `canceled`. The read itself is free. A generation it finds completed that your generate call did not see finish is charged here, once, at the quote that call was given (never twice, whichever call saw it finish). It never copies the media into your account, so the URLs it returns are Higgsfield's own and expire after about seven days.\n\nCalls `bowmark.providers.higgsfield.getRequestStatus`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<higgsfieldRequest>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"anyOf":[{"type":"string"},{"type":"object","properties":{"requestId":{"type":"string"}},"required":["requestId"],"additionalProperties":true}],"description":"TypeScript: `string | { requestId: string }`"}},"required":["args"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}}}}}