Generative Media API

Create media from a prompt and, when the user has opted in, a limited set of their Chainabit context. The API never accepts accountId, chainerId, or workspaceId in the body; those values come from the authenticated request.

Base Path

https://api.chainabit.com/api/v1/ai/generative-media

Create a Context Run

Description

Requires ai.contextMedia.generate and the matching media entitlement: ai.image.generate, ai.video.generate, or ai.audio.generate.

Request

• Headers: Authorization: Bearer <token>, Content-Type: application/json

sessionId is optional and ties the generation to an existing chat session; use the id from Create a Session's response (data.id) as $SESSION_ID.

{
  "prompt": "draw my life as a clean editorial poster",
  "mediaType": "image",
  "generationMode": "context_aware",
  "requestedContextSources": ["chainies", "bits"],
  "aspectRatio": "1:1",
  "sessionId": "$SESSION_ID"
}

requestedContextSources can include profile, preferences, settings, sessions, chainies, bits, memory, workspace, generation_history, and uploaded_media.

Response

{
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440010",
    "status": "completed",
    "mediaType": "image",
    "generationMode": "context_aware",
    "permissionRequired": false,
    "allowedContextSources": ["chainies", "bits"],
    "blockedContextSources": [],
    "resultMediaId": "550e8400-e29b-41d4-a716-446655440020",
    "errorCode": null,
    "createdAt": "2026-05-22T10:00:00Z",
    "updatedAt": "2026-05-22T10:00:08Z"
  }
}

If no requested source is allowed, the response uses status: "permission_required" and no personal context is retrieved.

Code Example

POST /ai/generative-media/context-runs
Authorization: Bearer $TOKEN
Content-Type: application/json

Read Job Status

Request

• Headers: Authorization: Bearer <token>
• Path params: jobId

The lookup is scoped to the authenticated user.

Response

A job owned by another user returns data: null.

Code Example

GET /ai/generative-media/context-runs/{jobId}
Authorization: Bearer $TOKEN

Read Permissions

Request

• Headers: Authorization: Bearer <token>

Response

{
  "data": {
    "allowPersonalizedGeneration": true,
    "perSource": {
      "profile": false,
      "preferences": true,
      "settings": false,
      "sessions": false,
      "chainies": true,
      "bits": true,
      "memory": false,
      "workspace": false,
      "generation_history": false,
      "uploaded_media": false
    },
    "capturedAt": "2026-05-22T10:00:00Z"
  }
}

Code Example

GET /ai/generative-media/permissions
Authorization: Bearer $TOKEN

Update Permissions

Request

• Headers: Authorization: Bearer <token>, Content-Type: application/json

{
  "personalizedGeneration": true,
  "chainies": true,
  "bits": true,
  "memory": false
}

Only included keys are updated. These consent flags are separate from chat memory preferences, so enabling AI memory does not automatically allow generative-media personalization.

Response

Code Example

PATCH /ai/generative-media/permissions
Authorization: Bearer $TOKEN
Content-Type: application/json