AssistantMessage

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/videogen-io/json-schema/videogen-io-assistant-message-schema.json",
  "title": "AssistantMessage",
  "description": "A single message in an assistant chat. Discriminated by `role`.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/videogen-io-assistant-api-openapi.yml#/components/schemas/AssistantMessage",
  "oneOf": [
    {
      "$ref": "#/$defs/AssistantInputMessage"
    },
    {
      "$ref": "#/$defs/AssistantOutputMessage"
    }
  ],
  "$defs": {
    "ApiError": {
      "type": "object",
      "description": "Standard error body returned with every non-2xx response (the `default` response of every operation). The HTTP status code conveys the error class; this body carries the details:\n\n- `400` invalid request, `401` missing or invalid API key, `403` not permitted (e.g. plan or add-on required, see `requirement`), `404` not found, `409` conflict, `429` rate limited or out of credits, `5xx` server error.\n\nCommon `code` values include `invalid_request`, `invalid_api_key`, `not_authorized`, `not_found`, `insufficient_credits`, and `rate_limited`. Always branch on `code` (and `requirement.type` when present) rather than parsing `message`.\n",
      "required": [
        "message"
      ],
      "properties": {
        "message": {
          "type": "string",
          "description": "Human-readable error description. For display and logging only; do not branch on its exact text."
        },
        "code": {
          "type": [
            "string",
            "null"
          ],
          "description": "Machine-readable error code in snake_case (e.g. `invalid_api_key`, `insufficient_credits`). `null` when no specific code applies."
        },
        "requirement": {
          "description": "What is needed to resolve the error. Present when the error can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on); `null` otherwise.",
          "anyOf": [
            {
              "$ref": "#/$defs/ErrorRequirement"
            },
            {
              "type": "null"
            }
          ]
        },
        "internalErrorCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "Opaque internal error code for debugging. Include this when contacting support. `null` when not applicable."
        }
      }
    },
    "AssistantAction": {
      "type": "object",
      "description": "An actionable widget the assistant offered on this turn. Act on it with `POST /v1/assistants/{assistantId}/actions/{actionId}` unless `requiresApp` is true.",
      "required": [
        "actionId",
        "kind",
        "label",
        "requiresApp"
      ],
      "properties": {
        "actionId": {
          "type": "string",
          "description": "Opaque id to pass to the act-on-action endpoint."
        },
        "kind": {
          "$ref": "#/$defs/AssistantActionKind"
        },
        "label": {
          "type": "string",
          "description": "Human-readable label describing what acting on this will do."
        },
        "requiresApp": {
          "type": "boolean",
          "description": "When true, this action can only be completed in the web app; open the assistant's `projectUrl` instead of calling the API."
        },
        "detail": {
          "$ref": "#/$defs/AssistantActionDetail",
          "description": "Optional extra data for rendering this action inline without opening the app."
        }
      }
    },
    "AssistantActionDetail": {
      "type": "object",
      "description": "Extra data for rendering this action inline (in a chat surface or integration) without opening the web app. Fields are populated only when relevant to the action's kind; all are optional.",
      "properties": {
        "summary": {
          "type": [
            "string",
            "null"
          ],
          "description": "Human-readable summary of the proposed plan or edit (for `APPROVE_PLAN` and `APPLY_EDIT` actions)."
        },
        "creditsRemaining": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Credits currently remaining on your team (for the usage/credits widget). A whole number of credits."
        },
        "estimatedCredits": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Estimated credit cost of the current workflow (for the cost-estimate widget). A whole number of credits."
        }
      }
    },
    "AssistantActionKind": {
      "type": "string",
      "description": "Normalized category of an actionable widget the assistant offered. `APPROVE_PLAN` accepts a proposed generation plan; `APPLY_EDIT` applies a proposed edit (e.g. a rewritten script); `RUN_TOOL` runs an inline tool; `GENERATE` starts building the video; `OPEN_IN_APP` requires the full web app — open the assistant's `projectUrl` instead of acting via the API.",
      "enum": [
        "APPROVE_PLAN",
        "APPLY_EDIT",
        "RUN_TOOL",
        "GENERATE",
        "OPEN_IN_APP"
      ]
    },
    "AssistantInputMessage": {
      "type": "object",
      "description": "A user-authored message in an assistant chat.",
      "required": [
        "messageId",
        "role",
        "status",
        "content",
        "attachments",
        "createdAt"
      ],
      "properties": {
        "messageId": {
          "type": "string",
          "description": "Opaque assistant message id (e.g. `vg_mesg_...`)."
        },
        "role": {
          "type": "string",
          "enum": [
            "user"
          ],
          "description": "Always `user`."
        },
        "status": {
          "$ref": "#/$defs/AssistantMessageStatus"
        },
        "content": {
          "type": "string",
          "description": "The user's message text."
        },
        "attachments": {
          "type": "array",
          "description": "Files attached to this message.",
          "items": {
            "$ref": "#/$defs/AssistantMessageAttachment"
          }
        },
        "createdAt": {
          "type": "integer",
          "description": "Seconds since epoch (Unix timestamp) when the message was created."
        }
      }
    },
    "AssistantMessageAttachment": {
      "type": "object",
      "description": "A file linked to an assistant chat message.",
      "required": [
        "displayName"
      ],
      "properties": {
        "fileId": {
          "type": [
            "string",
            "null"
          ],
          "description": "File id (e.g. `vg_file_...`) when the attachment is a storage file. `null` for attachments that are not resolvable storage files."
        },
        "displayName": {
          "type": "string",
          "description": "Human-readable name of the attachment."
        }
      }
    },
    "AssistantMessageStatus": {
      "type": "string",
      "description": "Lifecycle status of an assistant chat message. `pending` and `running` are in-progress; `succeeded`, `failed`, and `cancelled` are terminal.",
      "enum": [
        "pending",
        "running",
        "succeeded",
        "failed",
        "cancelled"
      ]
    },
    "AssistantOutputMessage": {
      "type": "object",
      "description": "An assistant-authored message in an assistant chat, including any suggestions or actions it offered.",
      "required": [
        "messageId",
        "role",
        "status",
        "content",
        "attachments",
        "workflowSuggestions",
        "actions",
        "generation",
        "error",
        "createdAt"
      ],
      "properties": {
        "messageId": {
          "type": "string",
          "description": "Opaque assistant message id (e.g. `vg_mesg_...`)."
        },
        "role": {
          "type": "string",
          "enum": [
            "assistant"
          ],
          "description": "Always `assistant`."
        },
        "status": {
          "$ref": "#/$defs/AssistantMessageStatus"
        },
        "content": {
          "type": [
            "string",
            "null"
          ],
          "description": "The assistant's text reply. `null` while `status` is `pending` or `running`; may be empty when the assistant only offered widgets."
        },
        "attachments": {
          "type": "array",
          "description": "Files attached to this message.",
          "items": {
            "$ref": "#/$defs/AssistantMessageAttachment"
          }
        },
        "workflowSuggestions": {
          "type": "array",
          "description": "Workflow starting points the assistant suggested on this message. Empty when none were offered.",
          "items": {
            "$ref": "#/$defs/AssistantWorkflowSuggestion"
          }
        },
        "actions": {
          "type": "array",
          "description": "Actionable widgets the assistant offered on this message (plans, edits, tools, generate). Empty when none were offered.",
          "items": {
            "$ref": "#/$defs/AssistantAction"
          }
        },
        "generation": {
          "description": "Present when this message kicked off a workflow run (via `autoGenerate` on start, or acting on a workflow suggestion): the workflow run to poll via `GET /v1/workflows/runs/{workflowRunId}`.",
          "anyOf": [
            {
              "$ref": "#/$defs/StartWorkflowRunResponse"
            },
            {
              "type": "null"
            }
          ]
        },
        "error": {
          "description": "Error details. `null` unless `status` is `failed`.",
          "anyOf": [
            {
              "$ref": "#/$defs/ApiError"
            },
            {
              "type": "null"
            }
          ]
        },
        "createdAt": {
          "type": "integer",
          "description": "Seconds since epoch (Unix timestamp) when the message was created."
        }
      }
    },
    "AssistantWorkflowSuggestion": {
      "type": "object",
      "description": "A starting-point workflow the assistant suggests for the conversation. Act on it with `POST /v1/assistants/{assistantId}/actions/{actionId}` to select the workflow and continue.",
      "required": [
        "actionId",
        "workflowType",
        "title",
        "description"
      ],
      "properties": {
        "actionId": {
          "type": "string",
          "description": "Opaque id to pass to the act-on-action endpoint to select this workflow."
        },
        "workflowType": {
          "$ref": "#/$defs/WorkflowType",
          "description": "Identifier of the suggested workflow."
        },
        "title": {
          "type": "string",
          "description": "Short human-readable name of the suggested workflow."
        },
        "description": {
          "type": "string",
          "description": "One-line explanation of what this workflow will do."
        }
      }
    },
    "ErrorRequirement": {
      "type": "object",
      "description": "What is needed to resolve an error, when it can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on or upgrading the plan).",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Machine-readable requirement type in snake_case (e.g. `purchase_add_on`, `upgrade_plan`)."
        },
        "details": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Key-value pairs with requirement-specific context (e.g. the add-on id to purchase)."
        }
      }
    },
    "StartWorkflowRunResponse": {
      "type": "object",
      "description": "Returned when a workflow run is accepted. Poll `GET /v1/workflows/runs/{workflowRunId}` or subscribe to webhooks for completion. When the start request set `autoExport: true`, wait until `status` is `succeeded` and use `downloadUrl`.",
      "required": [
        "workflowRunId",
        "projectId",
        "projectUrl",
        "remixActionIds"
      ],
      "properties": {
        "workflowRunId": {
          "type": "string",
          "description": "Opaque workflow run id (e.g. `vg_work_...`)."
        },
        "projectId": {
          "type": "string",
          "description": "Id of the project created for this workflow run (e.g. `vg_proj_...`)."
        },
        "projectUrl": {
          "type": "string",
          "format": "uri",
          "description": "Deep link to open this project in the VideoGen web editor. Not required for an API-only integration: store `projectId` and use the Projects API (export, remix, metadata). Use `projectUrl` when a person should open the project in the app to review or edit it manually. The project is visible only to members of your team and any project collaborators, the same access model as a project created in the dashboard."
        },
        "remixActionIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Opaque remix action ids (e.g. `vg_rmix_...`), one per `remixActions` entry in request order. Empty when no remix actions were requested. Each runs after the video is built; poll `GET /v1/projects/{projectId}/remix-actions`."
        }
      }
    },
    "WorkflowType": {
      "type": "string",
      "description": "Workflow type identifier.",
      "enum": [
        "SCRIPT_TO_VIDEO",
        "VOICEOVER_TO_VIDEO",
        "SLIDESHOW_TO_VIDEO",
        "STORYBOARD_TO_VIDEO",
        "PROMPT_TO_VIDEO_CLIP"
      ]
    }
  }
}