Asset Generation Guide

Learn how to set up your repository for AI-powered asset generation with Afila.

Getting Started

Afila generates AI images and videos from YAML files stored in your GitHub repository. The process works in three steps:

Install the Afila Connector GitHub App on your repository
Add a .afila/ folder with character, still, and scene YAML files
Submit a generation job from the Generation page

Generated assets are stored in the cloud and linked in your YAML files. Updated YAML is pushed to a new branch on your repository.

Afila Connector App

Afila needs read/write access to your repository to clone it, generate assets, and push results. This is handled through a GitHub App called Afila Connector.

Installation Steps

Go to github.com/apps/afila-connector
Click "Install" (or "Configure" if already installed)
Select the repositories you want to use with Afila — you can grant access to specific repos or all repos in your account
Click "Install" to confirm

Required Permissions

The Afila Connector requests the following permissions:

Permission	Access	Why
Contents	Read & Write	Clone repo and push updated YAML files
Metadata	Read	List repos and verify installation
Pull Requests	Read & Write	Create PRs with generated assets (future)

Note: If you're using an organization repository, an org admin may need to approve the installation.

Folder Structure

Create a .afila/ directory in the root of your repository with the following structure:

Repository layout

your-repo/
├── .afila/
│   ├── characters/
│   │   ├── hero.yaml
│   │   ├── villain.yaml
│   │   └── sidekick.yaml
│   ├── stills/
│   │   ├── park-adventure.yaml
│   │   └── battle-moment.yaml
│   ├── scenes/
│   │   ├── opening.yaml
│   │   ├── confrontation.yaml
│   │   └── finale.yaml
└── ...

Generated assets (images, videos) are stored in the cloud. Each YAML file's status.reference field will contain the URL to the generated asset after generation completes.

Character File Schema

Each YAML file in .afila/characters/ defines a character that will be used to generate a reference image. The filename (without extension) is used as the default character name.

.afila/characters/hero.yaml

# Required
name: Hero                          # Character name (overrides filename)
dataPrompt: >
  A young woman with silver hair and violet eyes,
  wearing a flowing blue cloak over leather armor,
  standing in a heroic pose, fantasy art style,
  detailed face, high quality

# Optional
dataPromptNegative: >
  blurry, low quality, deformed, extra limbs,
  bad anatomy, text, watermark

# Status — managed by Afila (do not edit manually)
# status:
#   success: true
#   reference: https://afilastore.blob.core.windows.net/assets/.../Hero.jpg
#   generatedTime: "2025-04-19T08:30:00.000Z"

Field Reference

Field	Type	Required	Description
name	string	Yes	Character name. Defaults to the filename if omitted. Must be alphanumeric (hyphens and underscores allowed), no spaces, max 30 characters.
dataPrompt	string	Yes	Prompt describing the character's appearance for image generation.
dataPromptNegative	string	No	Negative prompt — things to avoid in the generated image.
status	object	No	Managed by Afila. Tracks generation state including the URL to the generated asset. If `status.success` is `true`, the character is skipped on subsequent runs.

Tip: Be descriptive in your prompts. Include art style, clothing details, pose, and quality modifiers for best results.

Still File Schema

Each YAML file in .afila/stills/ defines a still image for high-quality AI image generation. Like scenes, stills can reference characters using @characterName in prompts — the character's generated image is automatically passed as a reference.

.afila/stills/park-adventure.yaml

type: still
metadata:
  name: park-adventure

spec:
  dataPrompt: >
    @Hero and @Sidekick running through a sunny park
    with tall oak trees, autumn leaves swirling in the air,
    warm golden hour lighting, ligne claire cartoon style

  dataPromptNegative: >
    blurry, low quality, deformed, realistic, dark

  # Generation options
  options:
    outputFormat: png               # jpg, png, or webp (default: png)
    aspectRatio: "16:9"             # see options table below

# Status — managed by Afila (do not edit manually)
# status:
#   success: true
#   reference: https://afilastore.blob.core.windows.net/assets/.../park-adventure.png
#   generatedTime: "2025-05-12T08:30:00.000Z"

Field Reference

Field	Type	Required	Description
name	string	Yes	Still name. Defaults to filename. Must be alphanumeric (hyphens and underscores allowed), no spaces, max 30 characters.
dataPrompt	string	Yes	Prompt describing the image to generate. Use `@characterName` to reference characters.
dataPromptNegative	string	No	Negative prompt — things to avoid in the generated image.
options	object	No	Generation settings: `outputFormat`, `aspectRatio`.
status	object	No	Managed by Afila. Tracks generation state. Completed stills are skipped on re-runs.

Options Reference

Option	Default	Values
outputFormat	png	`jpg`, `png`, `webp`
aspectRatio	16:9	`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`

Note: Stills are always generated at 2K resolution for optimal quality. Use @characterName references in your prompt to include character images as visual references for the AI.

Scene File Schema

Each YAML file in .afila/scenes/ defines a scene for multi-shot video generation. Characters are automatically detected from @characterName references in prompts and used as visual references. Enable audio for dialogue, sound effects, and ambient sound.

.afila/scenes/park-meeting.yaml

# Required
metadata:
  name: park-meeting

spec:
  dataPrompt: >
    @Hero meets @Sidekick in a sunny park,
    warm afternoon light, birds singing
  dataPromptNegative: dark, rainy, scary

  # Shots — individual video segments (max 6, total ≤ 15s)
  shots:
    - name: wide-shot
      dataPrompt: >
        Wide shot of a sunny park with a wooden bench,
        SFX: birds chirping, gentle breeze rustling leaves
      dataPromptNegative: ""
      duration: 5

    - name: meeting
      dataPrompt: >
        @Hero spots @Sidekick on the bench and runs over,
        @Hero says excitedly "There you are!",
        @Sidekick barks happily,
        SFX: footsteps on grass, joyful barking
      dataPromptNegative: ""
      duration: 5

  # Generation options
  options:
    duration: 10                    # 3–15 seconds (ignored when shots are used)
    aspectRatio: "16:9"             # 16:9, 9:16, or 1:1
    resolution: 1080p               # 1080p (default) or 720p
    enableAudio: true               # Dialogue, SFX, ambient (default: false)

Field Reference

Field	Type	Required	Description
name	string	Yes	Scene name. Defaults to filename. Alphanumeric, hyphens, underscores, max 30 characters.
dataPrompt	string	Yes	Overall scene description. Use `@characterName` to reference characters (max 4). Ignored when shots are used.
dataPromptNegative	string	No	Negative prompt for things to avoid.
shots	array	No	Individual video segments (max 6). Each has `name`, `dataPrompt`, and `duration` (1–14s). Total duration must not exceed 15s. When shots are used, the top-level `duration` is ignored.
options	object	No	Generation settings: `duration`, `aspectRatio`, `resolution`, `enableAudio`.
status	object	No	Managed by Afila. Tracks generation state. Completed scenes are skipped on re-runs.

Options Reference

Option	Default	Values
duration	10	3–15 seconds (ignored when shots are used)
aspectRatio	16:9	`16:9`, `9:16`, `1:1`
resolution	1080p	`1080p`, `720p`
enableAudio	false	`true` or `false` — enables dialogue, SFX, and ambient audio

Constraints

• Maximum 6 shots per scene

• Total shot duration must not exceed 15 seconds

• Each shot duration: 1–14 seconds (default: 3s)

• Maximum 4 character references (@characterName) per scene

• When shots are used, the top-level dataPrompt and duration are ignored

• Characters referenced with @name are automatically resolved to @image_1, @image_2, etc.

Audio Tips

When enableAudio: true, you can direct the soundscape in your prompts:

• Dialogue: Use quotes — @Hero says "Let's go!"

• Sound effects: Use SFX: prefix — SFX: thunder cracks, rain on roof

• Ambient sound: Describe the soundscape — quiet forest ambiance, distant river

Audio-enabled scenes cost more credits (see pricing below).

Running Generation

Once your repository is set up with the Afila Connector and .afila/ files:

Go to the Generation page
Paste your GitHub repository URL (e.g. https://github.com/user/my-book)
Click "Submit Generation Job"
Monitor progress on the same page

What happens during generation

1. The repo is cloned using the Afila Connector's access token

2. Character YAML files are parsed and images are generated (1 credit per image)

3. Still YAML files are parsed and high-quality images are generated (2 credits per still)

4. Scene YAML files are parsed and scenes are generated (8–13 credits per 5s depending on resolution and audio)

5. Generated assets are uploaded to cloud storage

6. YAML files are updated with status fields

7. Results are pushed to a new branch on your repository

Re-runs are incremental: Characters, stills, and scenes with status.success: true are automatically skipped. To regenerate an asset, remove the status block from its YAML file.

Credit Costs

Asset Type	Cost
Character image	1 credit
Still image (2K)	2 credits
Scene (1080p)	10 credits per 5 seconds
Scene (1080p + audio)	13 credits per 5 seconds
Scene (720p)	8 credits per 5 seconds
Scene (720p + audio)	10 credits per 5 seconds

Credits never expire. Get started with 10 free credits, or purchase 100 credits for $9.99 from the Credits page.