Skip to content

Make videos on the computer you already own. FreeVideo runs MiniMax H3 in as little as 8 GB of VRAM and 16 GB of RAM, and adapts its acceleration path to your hardware.

18.9 KB
Raw Blame
"""./freevideo agent ... — the agent API from a shell; every command prints JSON.

    ./freevideo agent status
    ./freevideo agent submit shot.json --wait
    ./freevideo agent batch storyboard.json --wait
    ./freevideo agent job j0123456789ab

Linux x86_64 uses ./freevideo; Windows uses freevideo.cmd. On macOS and other
Unix platforms, use the installed interpreter and source folder:
    env FREEVIDEO_AGENT=1 PYTHONPATH=/path/to/FreeVideo/engine-source \
        /path/to/installed/python -X utf8 -m freevideo_engine.agent.cli --root /path/to/FreeVideo status
"""
import argparse
import json
from pathlib import Path
import sys

from .client import ApiError, Client
from . import errors


def read(path):
    from . import schema
    text = sys.stdin.read() if path == '-' else Path(path).read_text(encoding='utf-8')
    value = json.loads(text)
    schema.validate({'type': 'object'}, value)
    return value


EXTRA_COMMANDS = {
    'inspect': ('POST', '/media/inspect'), 'contact-sheet': ('POST', '/media/contact-sheet'),
    'edit': ('POST', '/media/edit'), 'library': ('GET', '/library'),
    'queue': ('GET', '/queue'), 'hello': ('POST', '/connect/hello'),
    'connection-status': ('GET', '/connect/status'), 'openapi': ('GET', '/openapi.json'),
}


class Parser(argparse.ArgumentParser):
    def error(self, message):
        self.exit(2, errors.text(errors.build('invalid_request')) + '\n')


def build_parser():
    from . import schema
    parser = Parser(prog='./freevideo agent', description='Drive FreeVideo through its agent API.')
    parser.add_argument('--root', type=Path)
    parser.add_argument('--url')
    commands = parser.add_subparsers(dest='command', required=True)
    commands.add_parser('status', help='Readiness, limits, LoRAs, VLM and queue')
    commands.add_parser('guide', help='How to write H3 prompts')
    commands.add_parser('schema', help='JSON Schemas of jobs')
    command = commands.add_parser('install-skill', help='Copy the FreeVideo skill where Codex, Gemini CLI, Cursor and Claude Code read skills')
    command.add_argument('--target', choices=('agents', 'claude'), action='append', help='Default: both')
    command = commands.add_parser('capabilities', help='Read the studio capability cache')
    schema.cli_arguments(command, schema.contracts()['GET', '/capabilities']['query'])
    command = commands.add_parser('asset', help='Download a saved library video or thumbnail over HTTP')
    command.add_argument('id')
    command.add_argument('target', type=Path)
    command.add_argument('--thumbnail', action='store_true')
    for name, text in (('plan', 'Validate a job file and estimate it'), ('submit', 'Submit a job file (- = stdin)'),
                       ('batch', 'Submit {"jobs": [...]} with @ref links')):
        command = commands.add_parser(name, help=text)
        command.add_argument('file')
        if name != 'plan':
            command.add_argument('--wait', action='store_true', help='Wait for the job(s) and print the results')
        if name in ('submit', 'plan'):
            schema.cli_arguments(command, schema.generate(local=True))
        else:
            schema.cli_arguments(command, schema.batch_schema(local=True), exclude=('jobs',))
    for name in ('job', 'wait', 'cancel', 'resume'):
        command = commands.add_parser(name)
        command.add_argument('id')
        if name == 'wait':
            schema.cli_arguments(command, schema.obj({'timeout': schema.CLIENT_WAIT}))
        elif name == 'job':
            schema.cli_arguments(command, schema.contracts()['GET', '/jobs/{id}']['query'])
        elif name == 'resume':
            schema.cli_arguments(command, schema.contracts()['POST', '/jobs/{id}/resume']['body'])
    command = commands.add_parser('jobs')
    schema.cli_arguments(command, schema.contracts()['GET', '/jobs']['query'])
    command = commands.add_parser('upload', help='Copy a local media file into FreeVideo inputs')
    command.add_argument('path')
    command = commands.add_parser('imports', help='Bring local video or audio into the editing timeline')
    imports = command.add_subparsers(dest='operation', required=True)
    command = imports.add_parser('add', help='Upload content; poll imports list until ready before insert')
    command.add_argument('path')
    schema.cli_arguments(command, schema.obj({'ref': schema.REF}))
    imports.add_parser('list', help='List imported sources and preparation progress')
    command = commands.add_parser('generate-image', help='Generate or change a picture with the local image model')
    schema.cli_arguments(command, schema.image(), exclude=('kind',))
    command.add_argument('--wait', action='store_true', help='Wait for the picture and print the result')
    command = commands.add_parser('drama', help='Plan, start, review and finish a durable film')
    drama = command.add_subparsers(dest='operation', required=True)
    for name, (method, path, summary) in schema.DRAMA_OPERATIONS.items():
        sub = drama.add_parser(name, help=summary)
        if '{id}' in path:
            sub.add_argument('id')
        if '{shot}' in path:
            sub.add_argument('shot')
        if name in ('plan', 'start'):
            sub.add_argument('file', help='JSON production request with screenplay (- = stdin)')
        schema.cli_arguments(sub, schema.drama_schema(name))
    command = commands.add_parser('cast', help='Find, create and change character and setting cards')
    cast = command.add_subparsers(dest='operation', required=True)
    for name, (method, path, summary) in schema.CAST_OPERATIONS.items():
        sub = cast.add_parser(name, help=summary)
        if '{id}' in path:
            sub.add_argument('id')
        if name in ('create', 'update'):
            sub.add_argument('file', nargs='?', help='JSON card fields (- = stdin); options override them')
        schema.cli_arguments(sub, schema.cast_schema(name, local=True))
    command = commands.add_parser('projects', help='Read and edit timelines shared with the editor page')
    projects = command.add_subparsers(dest='operation', required=True)
    for name, (method, path, summary) in schema.PROJECT_OPERATIONS.items():
        sub = projects.add_parser(name, help=summary)
        if '{id}' in path:
            sub.add_argument('id')
        if name in ('create', 'write'):
            sub.add_argument('file', nargs='?', help='JSON {project, ref?} request (- = stdin); options override it')
        if name == 'operations':
            sub.add_argument('--operations-file', help='JSON array of operations (- = stdin)')
        schema.cli_arguments(sub, schema.project_schema(name))
    command = commands.add_parser('images', help='Edit pictures with the image editor\'s commands')
    images = command.add_subparsers(dest='operation', required=True)
    for name, (method, path, summary) in schema.IMAGE_OPERATIONS.items():
        sub = images.add_parser(name, help=summary)
        if '{id}' in path:
            sub.add_argument('id')
        if name in ('create', 'write'):
            sub.add_argument('file', nargs='?', help='JSON request (- = stdin); options override it')
        if name == 'operations':
            sub.add_argument('--operations-file', help='JSON array of operations (- = stdin)')
        schema.cli_arguments(sub, schema.image_schema(name))
    command = commands.add_parser('whitebox', help='Render a rough 3D white-model reference video in the user\'s open page')
    whitebox = command.add_subparsers(dest='operation', required=True)
    for name, (method, path, summary) in schema.WHITEBOX_OPERATIONS.items():
        sub = whitebox.add_parser(name, help=summary)
        if '{id}' in path:
            sub.add_argument('id')
        if name == 'submit':
            sub.add_argument('file', nargs='?', help='JSON {code, summary?} request (- = stdin); options override it')
        schema.cli_arguments(sub, schema.whitebox_schema(name))
    command = commands.add_parser('sessions', help='Share messages and plans with the user in a work conversation')
    sessions = command.add_subparsers(dest='operation', required=True)
    for name in ('list', 'create', 'events', 'post'):
        _, path, summary = schema.SESSION_OPERATIONS[name]
        sub = sessions.add_parser(name, help=summary)
        if '{id}' in path:
            sub.add_argument('id')
        if name == 'post':
            content = sub.add_mutually_exclusive_group(required=True)
            content.add_argument('--message', help='Text to send to the user')
            content.add_argument('--plan-file', help='JSON {shots, total_seconds?} plan (- = stdin)')
        else:
            schema.cli_arguments(sub, schema.session_schema(name))
    command = commands.add_parser('frame', help='Save a frame of a job or saved video')
    command.add_argument('source')
    schema.cli_arguments(command, schema.contracts()['POST', '/media/frame']['body'], exclude=('source',))
    for name, (method, path) in EXTRA_COMMANDS.items():
        command = commands.add_parser(name)
        definition = schema.contracts(local=True)[method, path]
        schema.cli_arguments(command, definition['query'] if method == 'GET' else definition['body'])
    return parser


def install_skill(argv):
    """Run `install-skill` without the job schemas, whose import loads the image libraries (numpy, Pillow).

    A deep installation folder on Windows cannot load those libraries by their full path, and copying
    the skill needs none of them. None where the command line is anything else."""
    parser = argparse.ArgumentParser(add_help=False)
    parser.add_argument('--root', type=Path)
    parser.add_argument('--url')
    parser.add_argument('command', nargs='?')
    known, rest = parser.parse_known_args(argv)
    if known.command != 'install-skill':
        return None
    parser = argparse.ArgumentParser(add_help=False, exit_on_error=False)
    parser.add_argument('--target', choices=('agents', 'claude'), action='append')
    try:
        args, extra = parser.parse_known_args(rest)
    except argparse.ArgumentError:
        return None
    if extra:
        return None
    from . import skill_install
    print(json.dumps({'installed': skill_install.install(tuple(args.target or ('agents', 'claude')))}, indent=2))
    return 0


def main(argv=None):
    for stream in (sys.stdin, sys.stdout):
        if hasattr(stream, 'reconfigure'):
            stream.reconfigure(encoding='utf-8')
    done = install_skill(sys.argv[1:] if argv is None else argv)
    if done is not None:
        return done
    from . import schema, spec
    parser = build_parser()
    args = parser.parse_args(argv)
    values = vars(args)

    def progress(view):
        value = view.get('progress') or {}
        line = '%s %s %s' % (view['id'], view['status'], value.get('label') or '')
        if value.get('fraction') is not None:
            line += ' %d%%' % round(100 * value['fraction'])
        print(line.rstrip(), file=sys.stderr, flush=True)

    def source(value):
        from .spec import JOB_ID, LIBRARY_ID
        return {'from_job': value} if JOB_ID.fullmatch(value) else {'library': value} if LIBRARY_ID.fullmatch(value) \
            else {'path': str(Path(value).resolve())} if Path(value).exists() else {'file': value}

    try:
        client = Client(args.url, root=args.root, name='freevideo-cli')
        if args.command in EXTRA_COMMANDS:
            method, path = EXTRA_COMMANDS[args.command]
            definition = schema.contracts(local=True)[method, path]
            shape = definition['query'] if method == 'GET' else definition['body']
            value = {k: values[k] for k in shape['properties'] if k in values}
            schema.validate(shape, value)
            result = client.get(path, **value) if method == 'GET' else client.post(path, value)
        elif args.command == 'status':
            result = client.capabilities()
        elif args.command == 'guide':
            result = client.guide()
        elif args.command == 'schema':
            result = client.schema()
        elif args.command == 'capabilities':
            fields = schema.contracts()['GET', '/capabilities']['query']['properties']
            result = client.capability_table(**{k: values[k] for k in fields if k in values})
        elif args.command == 'asset':
            result = dict(id=args.id, path=str(client.asset(args.id, args.target, thumbnail=args.thumbnail)))
        elif args.command == 'plan':
            value = read(args.file) | {k: values[k] for k in schema.generate()['properties'] if k in values}
            schema.validate_job(value, local=True)
            schema.preflight_submission(value)
            result = client.plan(value)
        elif args.command in ('submit', 'batch'):
            fields = schema.batch_schema() if args.command == 'batch' else schema.generate()
            value = read(args.file) | {k: values[k] for k in fields['properties'] if k in values}
            schema.validate(schema.batch_schema(local=True) if args.command == 'batch' else schema.job_schema(local=True), value)
            schema.preflight_submission(value)
            jobs = client.batch(value['jobs'], **({'ref': value['ref']} if 'ref' in value else {})) if args.command == 'batch' else \
                client.submit_takes(value, value['takes']) if value.get('takes', 1) > 1 else [client.submit(value)]
            if args.wait:
                jobs = [client.wait(job['id'], on_progress=progress) for job in jobs]
            result = jobs[0] if len(jobs) == 1 and args.command == 'submit' else {'jobs': jobs}
        elif args.command == 'generate-image':
            value = dict(kind='image', **{k: values[k] for k in schema.image()['properties'] if k in values})
            schema.validate_job(value)
            result = client.submit(value)
            if args.wait:
                result = client.wait(result['id'], on_progress=progress)
        elif args.command == 'job':
            result = client.job(args.id, **({'wait': values['wait']} if 'wait' in values else {}))
        elif args.command == 'wait':
            result = client.wait(args.id, values.get('timeout', 25), on_progress=progress)
        elif args.command == 'cancel':
            result = client.cancel(args.id)
        elif args.command == 'resume':
            result = client.resume(args.id, **({'ref': values['ref']} if 'ref' in values else {}))
        elif args.command == 'jobs':
            result = {'jobs': client.jobs(**{k: values[k] for k in schema.contracts()['GET', '/jobs']['query']['properties'] if k in values})}
        elif args.command == 'drama':
            method, path, _ = schema.DRAMA_OPERATIONS[args.operation]
            shape = schema.drama_schema(args.operation)
            value = read(args.file) if args.operation in ('plan', 'start') else {}
            value.update({k: values[k] for k in shape['properties'] if k in values})
            schema.validate(shape, value)
            for key in ('id', 'shot'):
                if '{' + key + '}' in path:
                    schema.validate(schema.PRODUCTION if key == 'id' else schema.SLUG, values[key])
                    path = path.replace('{' + key + '}', values[key])
            result = client.get(path, **value) if method == 'GET' else client.post(path, value)
        elif args.command == 'cast':
            method, path, _ = schema.CAST_OPERATIONS[args.operation]
            shape = schema.cast_schema(args.operation, local=True)
            value = read(args.file) if getattr(args, 'file', None) else {}
            value.update({k: values[k] for k in shape['properties'] if k in values})
            schema.validate(shape, value)
            if '{id}' in path:
                schema.validate(schema.CAST, values['id'])
                path = path.replace('{id}', values['id'])
            result = client.get(path, **value) if method == 'GET' else client.send(method, path, value)
        elif args.command in ('projects', 'images', 'whitebox'):
            table, shape_of, ident = {'projects': (schema.PROJECT_OPERATIONS, schema.project_schema, schema.PROJECT),
                                      'images': (schema.IMAGE_OPERATIONS, schema.image_schema, schema.IMAGE),
                                      'whitebox': (schema.WHITEBOX_OPERATIONS, schema.whitebox_schema, schema.WHITEBOX)}[args.command]
            method, path, _ = table[args.operation]
            shape = shape_of(args.operation)
            value = read(args.file) if getattr(args, 'file', None) else {}
            value.update({k: values[k] for k in shape['properties'] if k in values})
            if getattr(args, 'operations_file', None):
                text = sys.stdin.read() if args.operations_file == '-' else Path(args.operations_file).read_text(encoding='utf-8')
                value['operations'] = json.loads(text)
            schema.validate(shape, value)
            if '{id}' in path:
                schema.validate(ident, args.id)
                path = path.replace('{id}', args.id)
            result = client.get(path, **value) if method == 'GET' else client.send(method, path, value)
        elif args.command == 'sessions':
            method, path, _ = schema.SESSION_OPERATIONS[args.operation]
            shape = schema.session_schema(args.operation)
            if args.operation == 'post':
                if args.message is not None:
                    value = dict(type='message', text=args.message)
                else:
                    value = dict(type='plan') | read(args.plan_file)
                    schema.validate(schema.session_event(agent_only=True)['oneOf'][1], value)
                schema.validate(schema.session_event(agent_only=True), value)
            else:
                value = {k: values[k] for k in shape['properties'] if k in values}
            schema.validate(shape, value)
            if '{id}' in path:
                schema.validate(schema.SESSION, args.id)
                path = path.replace('{id}', args.id)
            result = client.get(path, **value) if method == 'GET' else client.post(path, value)
        elif args.command == 'upload':
            result = client.upload(args.path)
        elif args.command == 'imports':
            result = (client.import_media(args.path, **({'ref': args.ref} if hasattr(args, 'ref') else {}))
                      if args.operation == 'add' else client.get('/imports'))
        else:
            result = client.frame(source(args.source), values.get('at', 'last'))
    except ApiError as error:
        if error.inbox:
            print(json.dumps(dict(inbox=error.inbox), ensure_ascii=False, indent=1))
        print(str(error), file=sys.stderr)
        return 2
    except spec.SpecError as error:
        print(errors.text(errors.validation(error.errors)), file=sys.stderr)
        return 2
    except (ValueError, OSError):
        print(errors.text(errors.build('invalid_request')), file=sys.stderr)
        return 2
    print(json.dumps(result, ensure_ascii=False, indent=1))
    failed = isinstance(result, dict) and result.get('status') in ('failed', 'cancelled', 'interrupted')
    if failed and result.get('error'):
        print(errors.text(result['error']), file=sys.stderr)
    return 1 if failed else 0


if __name__ == '__main__':
    raise SystemExit(main())