Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/generation-sessions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Persistent generation sessions (proposal)

Create a session with an API key that has images or videos scope:

```http
POST /v1/generation-sessions
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"title":"Sequential shots"}
```

Save the returned `id` (for example, `gs_EXAMPLE`) and pass it to related image/video requests:

```json
{
"prompt": "Create the next shot using the established character design.",
"generation_session_id": "gs_EXAMPLE",
"async": true
}
```

Use `GET /v1/generation-sessions/{id}` to inspect state, busy status, active job and completed turn count. The upstream thread and account identifiers are not exposed. Session ownership is scoped to the creating API key.

Turns in one session execute exclusively and remain pinned to the same account. A busy session requeues waiting jobs without consuming an attempt. Omit the optional field to retain the existing independent-job behavior.

Session turns do not automatically retry generation or switch accounts. A failure after binding the upstream account, or a detected orphaned turn, conservatively marks the session uncertain. Inspect the existing job and upstream outcome before explicitly starting another session; a timeout does not establish that generation stopped. The inspection endpoint remains available for uncertain sessions.

## Review limitations

This is an opt-in API proposal. Retention expiry, explicit close/delete, and a user-facing reconciliation operation for uncertain sessions are not implemented. Upstream thread lifetime and exact visual continuity are not guaranteed. Crash recovery uses the existing stale-heartbeat sweep; it is not an immediate unlock guarantee. Interrupted/aborted turn behavior and multi-node races deserve further integration review.

Offline architecture tests cover ownership, exclusive locking, account affinity, busy requeueing, uncertainty, retained outputs, and exclusion of previous-turn media. Syntax and Studio checks also pass. No new upstream generation was submitted while preparing this contribution. Real MongoDB crash recovery and distributed load were not rerun for this PR.
49 changes: 35 additions & 14 deletions src/core/client.js
Original file line number Diff line number Diff line change
Expand Up @@ -1107,6 +1107,24 @@ class MuseClient extends EventEmitter {
options.signal?.throwIfAborted();
const onToken = typeof options === 'function' ? options : options.onToken;
const onEvent = options.onEvent;
const mediaPaths = p => [p?.image_path, ...(p?.data?.images || []).map(x => x.path), ...(p?.data?.videos || []).map(x => x.path)].filter(Boolean);
const previousPaths = new Set();
let previousUserIndex = -1;
if (options.sessionId && options.waitForKind) {
const history = await this.sendRequest('GET', `/chat/history?session_id=${options.sessionId}`, null, [], false, null, { signal: options.signal });
if (history.status !== 200 && history.status !== 404) throw new Error('Could not establish the retained session turn boundary.');
if (history.status === 200 && history.body) {
const events = JSON.parse(history.body).result?.chat_events || [];
previousUserIndex = events.map(e => e.role === 'user' || e.event_name === 'message.user').lastIndexOf(true);
for (const event of events) {
const p = event.payload || event;
for (const presentation of [p, ...(p.presentations || [])]) {
for (const path of mediaPaths(presentation)) previousPaths.add(path);
}
}
}
}
const isCurrentMedia = p => !mediaPaths(p).some(path => previousPaths.has(path));

return new Promise((resolve, reject) => {
let fullResponse = '';
Expand All @@ -1117,10 +1135,10 @@ class MuseClient extends EventEmitter {

const hasExpectedMedia = () => {
if (options.waitForKind === 'video') {
return presentations.some(p => p.kind === 'video' || p.data?.videos?.length > 0);
return presentations.some(p => (p.kind === 'video' || p.data?.videos?.length > 0) && mediaPaths(p).length > 0);
}
if (options.waitForKind === 'image') {
return presentations.some(p => p.kind === 'image' || p.data?.images?.length > 0);
return presentations.some(p => (p.kind === 'image' || p.data?.images?.length > 0) && mediaPaths(p).length > 0);
}
return false;
};
Expand Down Expand Up @@ -1236,7 +1254,7 @@ class MuseClient extends EventEmitter {
const handlePresentation = (payload, seq) => {
if (isDone || !isForSession(payload)) return;
// Do not treat browser_task as a media presentation
if (payload?.kind === 'browser_task' || payload?.data?.browser_task_id) return;
if (payload?.kind === 'browser_task' || payload?.data?.browser_task_id || !isCurrentMedia(payload)) return;

presentations.push(payload);
emit('presentation', payload);
Expand Down Expand Up @@ -1300,7 +1318,7 @@ class MuseClient extends EventEmitter {
// Extract any presentations from payload
if (Array.isArray(payload?.presentations)) {
for (const pres of payload.presentations) {
if (!presentations.some(p => p.id === pres.id || p.image_path === pres.image_path)) {
if (isCurrentMedia(pres) && !presentations.some(p => (p.id && p.id === pres.id) || (p.image_path && p.image_path === pres.image_path))) {
presentations.push(pres);
emit('presentation', pres);
}
Expand Down Expand Up @@ -1339,20 +1357,21 @@ class MuseClient extends EventEmitter {

// Find the LAST user message in this session
const lastUserIdx = evs.map(e => e.role === 'user' || e.event_name === 'message.user').lastIndexOf(true);
if (options.sessionId && options.waitForKind && lastUserIdx <= previousUserIndex) return;
const turnEvents = lastUserIdx !== -1 ? evs.slice(lastUserIdx + 1) : evs;

// Extract any presentations from ALL turn events (including delta.presentation)
for (const evItem of turnEvents) {
const p = evItem.payload || evItem;
if (evItem.event_name === 'delta.presentation' || p.kind === 'image' || p.kind === 'video' || p.data?.images?.length > 0 || p.data?.videos?.length > 0) {
if (!presentations.some(pr => (pr.id && pr.id === p.id) || (pr.image_path && pr.image_path === p.image_path) || (pr.data?.images?.[0]?.path && pr.data?.images?.[0]?.path === p.data?.images?.[0]?.path))) {
if (isCurrentMedia(p) && !presentations.some(pr => (pr.id && pr.id === p.id) || (pr.image_path && pr.image_path === p.image_path) || (pr.data?.images?.[0]?.path && pr.data?.images?.[0]?.path === p.data?.images?.[0]?.path))) {
presentations.push(p);
emit('presentation', p);
}
}
if (Array.isArray(p.presentations)) {
for (const pres of p.presentations) {
if (!presentations.some(pr => (pr.id && pr.id === pres.id) || (pr.image_path && pr.image_path === pres.image_path))) {
if (isCurrentMedia(pres) && !presentations.some(pr => (pr.id && pr.id === pres.id) || (pr.image_path && pr.image_path === pres.image_path))) {
presentations.push(pres);
emit('presentation', pres);
}
Expand Down Expand Up @@ -1645,8 +1664,8 @@ class MuseClient extends EventEmitter {
}

const chatResult = await this.chat(formattedPrompt, {
sessionId: null,
new_session: true,
sessionId: options.sessionId || null,
new_session: !options.sessionId,
ref_image: refImage,
ref_video: refVideo,
timeout: options.timeout || 180000,
Expand All @@ -1662,7 +1681,7 @@ class MuseClient extends EventEmitter {
// Find image presentation widget
const imagePres = chatResult.presentations.find(p => p.kind === 'image' || p.data?.images?.length > 0);
if (!imagePres) {
if (chatResult.sessionId) this.deleteSession(chatResult.sessionId).catch(() => {});
if (chatResult.sessionId && !options.retainSession) this.deleteSession(chatResult.sessionId).catch(() => {});
return {
success: false,
text: chatResult.text,
Expand All @@ -1683,11 +1702,12 @@ class MuseClient extends EventEmitter {
base64 = buffer.toString('base64');
}
} finally {
if (chatResult.sessionId) await this.deleteSession(chatResult.sessionId).catch(() => {});
if (chatResult.sessionId && !options.retainSession) await this.deleteSession(chatResult.sessionId).catch(() => {});
}

return {
success: true,
sessionId: chatResult.sessionId,
text: chatResult.text,
prompt,
path: imgPath,
Expand Down Expand Up @@ -1717,8 +1737,8 @@ class MuseClient extends EventEmitter {
}

const chatResult = await this.chat(formattedPrompt, {
sessionId: null,
new_session: true,
sessionId: options.sessionId || null,
new_session: !options.sessionId,
ref_image: refImage,
ref_video: refVideo,
timeout: options.timeout || 180000,
Expand All @@ -1739,7 +1759,7 @@ class MuseClient extends EventEmitter {
// Only this session's presentation/history may identify an output file.

if (!vidPath) {
if (chatResult.sessionId) await this.deleteSession(chatResult.sessionId).catch(() => {});
if (chatResult.sessionId && !options.retainSession) await this.deleteSession(chatResult.sessionId).catch(() => {});
return {
success: false,
text: chatResult.text,
Expand All @@ -1757,11 +1777,12 @@ class MuseClient extends EventEmitter {
base64 = buffer.toString('base64');
}
} finally {
if (chatResult.sessionId) await this.deleteSession(chatResult.sessionId).catch(() => {});
if (chatResult.sessionId && !options.retainSession) await this.deleteSession(chatResult.sessionId).catch(() => {});
}

return {
success: true,
sessionId: chatResult.sessionId,
text: chatResult.text,
prompt,
path: vidPath,
Expand Down
18 changes: 18 additions & 0 deletions src/docs/openapi.js
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,16 @@ function buildOpenApiSpec() {
{ name: 'Health', description: 'Liveness and readiness probes.' }
],
paths: {
'/v1/generation-sessions': {
post: { tags: ['Generation sessions'], summary: 'Create a retained image/video project session (images or videos scope; no upstream generation)',
requestBody: { required: true, content: json({ type: 'object', additionalProperties: false, properties: { title: { type: 'string', maxLength: 200 } } }) },
responses: { 201: { description: 'Session created', content: json(ref('GenerationSession')) }, 401: resp('Error') } }
},
'/v1/generation-sessions/{id}': {
get: { tags: ['Generation sessions'], summary: 'Inspect an owned generation session',
parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
responses: { 200: { description: 'Session state (upstream account/session identifiers are private)', content: json(ref('GenerationSession')) }, 404: resp('Error') } }
},
// ------------------------------------------------------------------ Chat
'/v1/chat/completions': {
post: {
Expand Down Expand Up @@ -448,11 +458,17 @@ function buildOpenApiSpec() {
}
},

GenerationSession: {
type: 'object', properties: { id: { type: 'string' }, object: { const: 'generation_session' }, title: { type: 'string' },
state: { type: 'string', enum: ['ready', 'uncertain'] }, busy: { type: 'boolean' }, active_job_id: { type: ['string', 'null'] },
turn_count: { type: 'integer' }, created_at: { type: 'string', format: 'date-time' }, updated_at: { type: 'string', format: 'date-time' } }
},
ImageGenerationRequest: {
type: 'object',
required: ['prompt'],
additionalProperties: false,
properties: {
generation_session_id: { type: 'string', pattern: '^gs_[A-Za-z0-9_-]+$', description: 'Retain and continue one upstream session on its owning account. Turns execute exclusively. Interrupted turns mark the session uncertain and are not automatically retried.' },
prompt: { type: 'string', minLength: 1, maxLength: 4000 },
model: { type: 'string' },
n: { type: 'integer', const: 1 },
Expand Down Expand Up @@ -480,6 +496,7 @@ function buildOpenApiSpec() {
required: ['prompt'],
additionalProperties: false,
properties: {
generation_session_id: { type: 'string', pattern: '^gs_[A-Za-z0-9_-]+$', description: 'Retain and continue one upstream session on its owning account. Turns execute exclusively. Interrupted turns mark the session uncertain and are not automatically retried.' },
prompt: { type: 'string', minLength: 1, maxLength: 4000 },
model: { type: 'string' },
aspect_ratio: { type: 'string', enum: ['16:9', '9:16', '1:1'], default: '16:9' },
Expand All @@ -496,6 +513,7 @@ function buildOpenApiSpec() {
properties: {
id: { type: 'string' },
object: { const: 'job' },
generation_session_id: { type: ['string', 'null'] },
type: { type: 'string', enum: ['image', 'video'] },
status: { type: 'string', enum: ['queued', 'running', 'succeeded', 'failed', 'canceled'] },
progress: { type: 'integer', minimum: 0, maximum: 100, description: 'Estimated completion percentage.' },
Expand Down
17 changes: 17 additions & 0 deletions src/models/GenerationSession.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
'use strict';
const mongoose = require('mongoose');
const { randomUUID } = require('crypto');
const { generateId } = require('../utils/crypto');
const schema = new mongoose.Schema({
_id: { type: String, default: () => generateId('gs') },
api_key_id: { type: String, required: true, index: true },
title: { type: String, default: '', maxlength: 200 },
session_id: { type: String, default: randomUUID, required: true },
account_id: { type: String, default: null },
state: { type: String, enum: ['ready', 'uncertain'], default: 'ready' },
active_execution: { type: String, default: null },
active_job_id: { type: String, default: null },
upstream_started: { type: Boolean, default: false },
turn_count: { type: Number, default: 0 }
}, { timestamps: { createdAt: 'created_at', updatedAt: 'updated_at' }, versionKey: false });
module.exports = { GenerationSession: mongoose.models.GenerationSession || mongoose.model('GenerationSession', schema) };
2 changes: 2 additions & 0 deletions src/models/Job.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ const JobSchema = new mongoose.Schema(
api_key_id: { type: String, required: true },
status: { type: String, enum: JOB_STATUSES, default: 'queued' },
prompt: { type: String, required: true, maxlength: 4000 },
generation_session_id: { type: String, default: null },
session_wait_until: { type: Date, default: null },
params: {
aspect_ratio: { type: String, default: null },
duration: { type: Number, default: null },
Expand Down
2 changes: 2 additions & 0 deletions src/routes/generation.js
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@ async function submitGeneration(req, res, { type, sync, params, references, onSu
await dispatcher.assertCanEnqueue(type, apiKey);
const webhookUrl = body.webhook_url ? webhook.validateWebhookUrl(body.webhook_url) : null;

if (body.generation_session_id) await require('../services/generationSessions').get(body.generation_session_id, apiKey._id);
const reference = { image_file_id: null, video_file_id: null };
if (references.image) {
const doc = await media.resolveReference(references.image, { expectedKind: 'image', apiKeyId: apiKey._id, param: 'reference_image' });
Expand All @@ -77,6 +78,7 @@ async function submitGeneration(req, res, { type, sync, params, references, onSu
apiKey,
type,
prompt: body.prompt,
generationSessionId: body.generation_session_id,
params,
reference,
webhookUrl,
Expand Down
20 changes: 20 additions & 0 deletions src/routes/generationSessions.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
'use strict';
const express = require('express');
const { GenerationSession } = require('../models/GenerationSession');
const sessions = require('../services/generationSessions');
const { requireScope } = require('../middleware/auth');
const { validate } = require('../middleware/validate');
const { z } = require('./helpers');
const { ApiError, ErrorCodes } = require('../errors');
const router = express.Router();
router.use(requireScope('images', 'videos'));
router.post('/', validate(z.object({ title: z.string().trim().max(200).default('') }).strict()), async (req, res) => {
const doc = await GenerationSession.create({ api_key_id: req.auth.apiKey._id, title: req.valid.body.title });
res.status(201).json(sessions.serialize(doc));
});
router.get('/:id', async (req, res) => {
const doc = await GenerationSession.findOne({ _id: req.params.id, api_key_id: req.auth.apiKey._id }).lean();
if (!doc) throw new ApiError(ErrorCodes.RESOURCE_NOT_FOUND);
res.json(sessions.serialize(doc));
});
module.exports = router;
1 change: 1 addition & 0 deletions src/routes/images.js
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ const router = express.Router();
const IMAGE_ASPECT_RATIOS = ['1:1', '16:9', '9:16', '4:3', '3:4', '3:2', '2:3'];

const imageRequestSchema = z.object({
generation_session_id: z.string().regex(/^gs_[A-Za-z0-9_-]+$/).optional(),
prompt: z.string().trim().min(1).max(4000),
model: z.string().max(64).optional(),
n: z.literal(1).optional().describe('Only one image per request is supported.'),
Expand Down
1 change: 1 addition & 0 deletions src/routes/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ v1.use('/files', filesRouter);

// Every other endpoint requires an API key and is rate limited per key.
v1.use(authenticate, keyRateLimit);
v1.use('/generation-sessions', require('./generationSessions'));
v1.use('/images', imagesRouter);
v1.use('/videos', videosRouter);
v1.use('/jobs', jobsRouter);
Expand Down
1 change: 1 addition & 0 deletions src/routes/videos.js
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ const VIDEO_ASPECT_RATIOS = ['16:9', '9:16', '1:1'];

const videoRequestSchema = z
.object({
generation_session_id: z.string().regex(/^gs_[A-Za-z0-9_-]+$/).optional(),
prompt: z.string().trim().min(1).max(4000),
model: z.string().max(64).optional(),
aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).default('16:9'),
Expand Down
2 changes: 2 additions & 0 deletions src/serializers.js
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ function serializeJob(doc) {
id: doc._id,
object: 'job',
type: doc.type,
generation_session_id: doc.generation_session_id || null,
status: doc.status,
progress: doc.progress ?? 0,
progress_text: doc.progress_text || null,
Expand All @@ -56,6 +57,7 @@ function serializeJob(doc) {
},
reference: {
image_file_id: doc.reference?.image_file_id || null,
...(doc.reference?.images?.length ? { images: doc.reference.images.map(item => ({ file_id: item.file_id, label: item.label, role: item.role })) } : {}),
...(doc.type === 'video' ? { video_file_id: doc.reference?.video_file_id || null } : {})
},
output,
Expand Down
Loading