File.generate · SalesBuilder

POST https://api.sb/{your-domain}/files/generate

Its Inputs, Outputs, Effects and guards quote the hub’s File.generate; this page adds what each Venue honors, its limits and a worked call.

Inputs

Name	Type	Default	Meaning
`kind`	`string`	Required	What to make.
`prompt`	`text`	Required	What to make, or for `speech` the text to speak.
`references`	`File[]`	`[]`	Files the output follows, such as a product photo or a first frame. Unset: none; the output follows the prompt alone.
`voice`	`Voice`	`your Brand’s Voice`	The Voice that speaks, for `speech`. Unset: the Brand’s Voice, when it has one.
`format`	`json`	`{ aspect: '1:1' }`	Aspect ratio, resolution, duration and file type. Unset: square, at the network’s largest size for an image; 5 seconds for a clip.

Outputs

Field	Type	What `null` means
`file`	`File`	Never null: the File, its bytes copied into Storage before the Action is done.
`file.name`	`string`	Never null: a name made from the prompt, such as `renewal-notice-card.png`.
`file.contentType`	`string`	Never null: `image/png`, `video/mp4`, `audio/mpeg`.

Effects

Action class

None: no approval rule names it, so it runs within its seat’s Permissions and Limits

Modes

try: Checks the prompt, the references and the Voice, and returns the File as it would be named and typed; nothing is generated or billed.
send: Returns a pending Action at once; File.generated fires when the bytes are in Storage.
do: Waits for the bytes, seconds for an image and up to a few minutes for a clip, and returns the File.

Idempotency

Only with a key: the same Idempotency-Key and input return the first Action, and the same key with other input returns 409. A repeat with the same key returns the first File and bills nothing; a new key generates again.

Saved or shared

The File in Storage, with its prompt, references, Voice and route recorded as provenance. A failed or declined generation saves nothing and costs nothing.

Emits

File.generated with { file, kind, prompt }

Performed by

Content lead

Price

About 1.2¢ a File. At most $1.20 a File. Free: a generation that fails or is declined, try mode.

On each Venue

It acts on your own records and reaches no Venue, so every account answers the same way.

What try does

Runs every check the call meets and returns the record as it would be; nothing is stored, sent or posted.

Refuses when

Check	Error	Fix	Then call
An invented testimonial, a synthetic person speaking as a customer, or a face or voice with no yes	`synthetic-media`	Use a real customer’s words with their yes, or show the product instead.	`Content.draft`
A cut with an attendee's face, voice or full name and no recorded Consent	`face-voice-consent`	Record the attendee's Consent, or cut them from the piece.	`Consent.create`
A data call whose price for what you asked is above its `maxCost`, checked before anything is spent	`max-cost`	Lower `limit`, or raise `maxCost` to the price the refusal’s detail quotes.	`Organization.find`

The synthetic-media payload

JSON

{
  "type": "https://startupbuilder.dev/errors/synthetic-media",
  "title": "Synthetic media",
  "status": 422,
  "detail": "An invented testimonial, a synthetic person speaking as a Customer, or a face or voice with no yes.",
  "fix": "Use a real Customer’s words with their yes, or show the product instead.",
  "next": {
    "verb": "Content.draft",
    "input": {}
  },
  "instance": "https://api.sb/leaseline.app/actions/action_1"
}

When it waits

In send mode it returns a pending Action, reason: 'running' until the bytes are in Storage; canceling it cancels the generation, and File.generated delivers the result.

TypeScript

await $.Watch.create({
  selector: 'File.generated',
  url: 'https://leaseline.app/hooks/sb'
})

Example

A refusal: its reference shows a face with no recorded Consent, so the call refuses before anything is generated.

You, to your agent

Make a square image for the renewal-notice post: a calendar page with a
notice 60 days out, in our brand colors, for `references:
['file_test_face']`.

Response, in try mode

{
  "type": "https://startupbuilder.dev/errors/face-voice-consent",
  "title": "No Consent for face or voice",
  "status": 422,
  "detail": "A cut with an attendee's face, voice or full name and no recorded Consent.",
  "fix": "Record the attendee's Consent, or cut them from the piece.",
  "next": {
    "verb": "Consent.create",
    "input": {}
  },
  "instance": "https://api.sb/leaseline.app/actions/action_1"
}

To retry, send the same Idempotency-Key: the retry returns the first answer for $0. A new key reads again.

Test values

A sk_test_ key answers these the same way every time, at $0 (every test value).

Test value	Always returns	What it is for
`prompt: 'test image'`	`{"file":{"name":"test-image.png","contentType":"image/png"}}`	Returns the same 1,024-pixel test image every time, free, so the post that uses it can be built.
`references: ['file_test_face']`	Refuses with `face-voice-consent`	Its reference shows a face with no recorded Consent, so the call refuses before anything is generated.

Used by

Workflows: Launch kit
Agent tasks: Launch day · Ad kit · Message test
Jobs: Make content

InputsCopy Anchor Link

OutputsCopy Anchor Link

EffectsCopy Anchor Link

On each VenueCopy Anchor Link

What try doesCopy Anchor Link

Refuses whenCopy Anchor Link

When it waitsCopy Anchor Link

ExampleCopy Anchor Link

Used byCopy Anchor Link

RelatedCopy Anchor Link