AI Media Generation API
The AI Media Generation API lets authenticated B2B admins create and monitor short reusable image and video generation jobs for GOFA authoring workflows.
This API is designed for B2B CMS usage such as AI Move and AI Training authoring. Jobs are created asynchronously and become available after the generated media has been processed into the client's private media library.
This API is intended for authenticated B2B admin users. Requests must come from a valid admin session or include a valid Firebase user token with admin access for the current client.
Authentication
Use the authenticated admin user's Firebase token in the Authorization header:
Authorization: Bearer <firebase_id_token>
Requests without a valid admin identity return 401 or 403.
Job Endpoints
POST /api/b2b/ai/media-generation/jobs
Creates a new asynchronous media-generation job for the current client. The legacy /api/b2b/ai/video-generation/jobs path remains available for backward compatibility, but new integrations should use the media-generation path.
{
"mediaType": "video",
"module": "aiMove",
"targetType": "exercise-cover",
"targetEntityId": "exercise_demo_001",
"promptPreset": "exercise-cover-motion",
"promptInput": {
"promptText": "A coach demonstrating a gentle standing warm-up with clean studio lighting and clear side-to-side arm motion.",
"context": {
"name": "Standing Warm Up",
"category": "Mobility",
"description": "Used as a reusable exercise cover clip in the B2B catalog."
}
},
"requestedSettings": {
"aspectRatio": "16:9"
}
}
For image generation, set mediaType to image and use an image preset such as image-exercise-thumbnail, image-coach-portrait, image-promo-visual, image-wellness-background, or image-app-hero. Reference-based image or video generation can include referenceImages, where each item contains a public url, optional name, and mediaType: "image".
GOFA admins can optionally provide requestedSettings such as model, generationMode, durationSeconds, aspectRatio, resolution, and seed. Other clients may send the same shape, but the service can apply standard presets based on the current client policy.
POST response
201 Created: Returns the createdjoband its initial execution state.202 Accepted: Job was saved, but background queueing failed. The returned job is markedfailedand can be retried after the queue is available.400 Bad Request: Validation failed.
The execution.queueEventId value is an opaque identifier that can be used when correlating a newly created job with server-side processing logs.
{
"job": {
"jobId": "9dd43dd4-92a9-4cd2-a7c3-2e2c1d0cbf7a",
"clientId": "gofa",
"mediaType": "video",
"module": "aiMove",
"targetType": "exercise-cover",
"targetEntityId": "exercise_demo_001",
"status": "queued",
"promptPreset": "exercise-cover-motion",
"promptInput": {
"promptText": "A coach demonstrating a gentle standing warm-up with clean studio lighting and clear side-to-side arm motion.",
"context": {
"name": "Standing Warm Up",
"category": "Mobility",
"description": "Used as a reusable exercise cover clip in the B2B catalog."
}
},
"referenceImages": [],
"normalizedPrompt": "Exercise Cover Motion.\nCreate a short exercise cover motion clip that communicates the exercise category at a glance.",
"policyProfile": "internal-gofa",
"generationMode": "t2v",
"model": "bytedance/seedance-2.0-fast",
"durationSeconds": 5,
"aspectRatio": "16:9",
"resolution": "854x480",
"providerGenerationId": null,
"providerCostUsd": null,
"billingPresetKey": "exercise_cover_motion_short",
"warnings": [],
"cloudflareVideoId": null,
"mediaAssetId": null,
"resultVideoUrl": null,
"resultImageUrl": null,
"resultMediaType": null,
"errorMessage": null,
"attemptCount": 0,
"createdAt": "2026-05-09T11:20:00.000Z"
},
"execution": {
"mode": "queued",
"processor": "queue",
"queueEventId": "b2b-ai-media-generation:gofa:9dd43dd4-92a9-4cd2-a7c3-2e2c1d0cbf7a:8b8c3f8a-2677-4352-a27f-1f742cc9b42b"
}
}
GET /api/b2b/ai/media-generation/jobs
Lists media-generation jobs for the current client.
Query parameters
status: Optional. Filter byqueued,processing,uploading,available,failed, orattached.query: Optional text search across job id, prompt text, target entity id, and model.limit: Optional result cap. Maximum100.
GET /api/b2b/ai/media-generation/jobs?status=available&limit=20
GET response
200 OK: Returns ajobsarray.
GET /api/b2b/ai/media-generation/jobs/[jobId]
Returns one media-generation job for the current client.
GET response for a single job
200 OK: Returns thejobobject.404 Not Found: Job not found.
DELETE /api/b2b/ai/media-generation/jobs/[jobId]
Deletes a queued or failed media-generation job. Queued jobs are cancelled before background processing starts; failed jobs are removed from the job history.
DELETE response
200 OK: Job was removed.404 Not Found: Job not found.409 Conflict: Job is not queued or failed and cannot be deleted.
POST /api/b2b/ai/media-generation/jobs/[jobId]/retry
Requeues a failed or previously completed job for another generation attempt.
POST response for retry
200 OK: Returns the updatedjoband queued execution state.404 Not Found: Job not found.
Successful retry responses also include execution.queueEventId for correlating that retry attempt with processing logs.
Job Lifecycle
The API returns jobs with lifecycle states such as:
queued: accepted and waiting for background execution.processing: prompt generation and provider request in progress.uploading: generated output is being processed into the client video library.available: the generated image or video is ready for selection and reuse.failed: generation or processing failed.attached: the generated asset was explicitly selected for content use.
Generated media is not automatically attached to a content record. Admins are expected to review and explicitly choose a finished asset before using it in authoring flows. Video jobs return resultVideoUrl when available; image jobs return resultImageUrl and mediaAssetId when available.
This API does not guarantee immediate availability. Clients should poll the job endpoint until the status becomes available or failed.