Quick generate: skipping the conversation loop

Not every generation is a conversation. POST /api/v1/agentic/quick-generate runs one image or video generate without loading history, memories, a brand kit, or a chat model. You send a type, a prompt, and a user. You get back the same dispatch receipt a generate tool would have returned inside chat. No conversation_id. No follow-up. The next call does not remember this one.

That is the point. Chat exists for back-and-forth: "warmer," "the other bottle," "now caption it." Quick generate exists for the script that already knows the prompt.

What the endpoint actually does

Required: type, prompt, user_id. type is image or video. Anything else is a 400. Photo-to-video belongs on the agent path or a generate-video-from-image tool, not here.

Optional, with the defaults the handler actually applies:

Field	Default	Notes
models	First model in the live image or video catalog	Pin this. An unnamed first catalog entry is a moving target.
num_images	1	Image only.
aspect_ratio	"1:1"	Set "9:16" when you mean a reel, or you will crop a square later.
style	omitted	Image only, passed through.
duration	"5"	Video, seconds as a string. Confirm the named model actually allows 5.
resolution	"1080p"	Video.
token	omitted	Send the user session or API key the same way you do for chat.

The handler picks generate_images or generate_videos, calls the same executor chat uses, and returns:

{
  "success": true,
  "type": "image" | "video",
  "function_result": { ... },
  "generations": [ ... ]
}

generations is filled when the executor reports generation_started. You are looking at request ids and pending rows, not a finished CDN URL. Poll like you would after any other generate. This is not a synchronous render endpoint.

Auth, credits, and rate limit match agent chat: same credit middleware, 60 requests per minute per user. Every call costs generation credits. There is no daily allowance. Pricing is the tariff. The app's own client gives the HTTP call a 90-second timeout, which is plenty for a dispatch and too short if you mistakenly expected the video file in the same response.

When the conversation is overhead

Use quick generate when the brief is already compiled and you do not need the agent to argue with it.

Batch stills from a spreadsheet. Each row is a prompt, an aspect ratio, a named model. Loop. Collect request_ids. Do not open a chat per row; you would pay chat-token credits to have the model say "sure, generating that now" a hundred times.

A CI job that needs one clip. Prompt and model are in the workflow file. You want a receipt, then you poll. Chat would load memories and the catalog context for no benefit.

Fan-out on purpose. models is an array. Pass three named image models, get three dispatches from one call, compare. That is the same fan-out the generate tools support. Check the total first if the batch is large. estimate_cost in chat is the itemised version when you are already in a conversation.

A button that is not a chatbot. "Make a 1:1 product still from this prompt" does not need a thread. Wire the button here. Put a chat behind "make it more like the last campaign."

Pin the model. If models is missing or empty, the handler takes imageModels[0] or videoModels[0] from the live catalog. That is fine for a scratch test and a defect in production: yesterday's first entry is not a creative decision. The model catalog is where you look the names up; the text-to-video tool is the product surface that already assumes a pinned choice.

A scripted call looks like this:

POST /api/v1/agentic/quick-generate
{
  "type": "video",
  "prompt": "locked-off tripod, bottle on wet stone, warm sidelight, 9:16, no text",
  "user_id": "<id>",
  "models": ["<the exact catalog name you settled on>"],
  "aspect_ratio": "9:16",
  "duration": "5",
  "resolution": "1080p"
}

Then poll. Do not sit on the HTTP response waiting for MP4 bytes.

A 200 from this endpoint is a dispatch receipt. Typical next steps:

1. Read generations (or function_result) for request_ids.
2. Poll GET /api/v1/status/:requestId until completed or failed. Transient failures are classified separately from permanent ones; retry only the transient kind.
3. Take result_url from the completed payload. There is no customer webhook that will POST it to you.
4. If the next step is captions, a merge, or a post, you are now out of quick-generate territory. Hand the URL to chat or to a named background task.

Do not send conversation_id, chat_model, or workflow_theme here. They are ignored because the handler never reads them. Extra fields are not a way to smuggle context in.

When you still need chat

Skip quick generate the moment the next action depends on something the last action learned.

Revision. "Make it warmer" needs the previous generate in history. Quick generate has no history. You would have to re-send the whole prompt with the adjective bolted on, and you would still not have the last still as a reference image unless you pass it yourself (and this endpoint does not take image_url in the handler).

Multi-step. Captions, merge, post, notify, wait. That is spawn_background_task or a full agent turn, not a one-shot. Quick generate will not wait for the clip and will not call a second tool.

Memory and brand. Chat loads the brand kit, long-term memories, the conversation media library, and the model catalog into the prompt. Quick generate loads none of that. If the still has to match a stored palette, either put the palette in the prompt you send, or use chat.

Judgement gates. "Generate four, I'll pick" is a conversation. The pick is the point.

A chat model you chose for reasoning. Quick generate does not take chat_model. There is no reasoner. The generate model is the only model in play.

If you are already in a streaming chat because a person is briefing, stay there. Streaming versus blocking is the choice inside that loop. Quick generate is the choice to leave the loop.

A reasonable split for a production script:

1. Humans iterate the look in agent chat until the prompt and model are stable.
2. Freeze both in config.
3. Nightly batch hits quick generate with that pair.
4. Anything that needs a follow-up (caption, post, "like yesterday but outdoor") goes back to chat or a named background task.

FAQ

Does quick generate use my brand kit?

No. It never loads conversation context. If the kit matters, put the relevant constraints in the prompt, or send the request through chat so the kit is injected.

Can I pass several models in one call?

Yes. models is an array and is forwarded to generate_images or generate_videos. Each named model is a dispatch and a charge. An empty or omitted array falls back to the first catalog entry for that type, which you should not rely on.

Why did I get a pending generation instead of a URL?

The executor dispatches and returns generation_started. Quick generate surfaces that. Poll the status endpoint for the request_id, or watch the library. Treat the 200 as "queued," not "rendered."

Is this cheaper than asking in chat?

You skip chat-token credits because no chat model runs. You do not skip generation credits. A 5-second clip costs what that model costs on pricing either way. The saving is the reasoner, not the render.