Create Forms with AIPro

Use Create with AI to build an editable Freeform form from a description. In Freeform 5.17+, you can also attach PDFs, images, or screenshots of an existing form and ask AI to recreate its structure with native Freeform fields.

The generator uses an enabled AI integration already configured in Freeform. SolspaceAI uses its existing authorization and credits and chooses the model automatically. Other providers use the credentials and model configured on their integration. Text-based generation remains available when an integration does not support reference files.

Before You Start

• Configure and enable an AI integration. Freeform's built-in AI integrations require Pro.
• For reference files, choose a compatible integration and model from the compatibility guidance below.
• Your control-panel user needs Create Forms and Access Integrations permissions, along with access to the Forms area.
• Craft needs a working asynchronous queue runner. See Background Generation for setup and recovery.

Create a Form

1

Open Freeform → Forms and click Create with AI.

2

Choose an AI Integration. For OpenAI, Anthropic, and Gemini, the dialog shows the configured model beneath the reference-file controls. SolspaceAI selects its model automatically.

3

To recreate a form, choose or drop files under Reference form (optional). Use the up/down buttons to arrange multiple files in reading order, or remove any you do not want included. For a form created entirely from a prompt, leave this area empty and fill in Describe your form.

4

When files are attached, use Additional instructions (optional) to explain what to include, omit, or change. You can generate from files alone. Enter a Form name (optional) if you want to suggest a name.

5

Click Generate form. Freeform queues generation and checks its progress, then opens the completed form in the builder. Review the fields, configure its settings and behavior, then preview and test it before publishing.

For example, a text prompt could be:

Create an event registration form with name, email, dietary requirements, and a choice of morning or afternoon session.

With a reference attached, additional instructions could be:

Recreate pages 1–2. Omit the office-use section and add an email field after the applicant's name.

You can close the dialog while generation continues. Reopen Create with AI in the same browser tab to resume checking progress. Closing the dialog does not cancel the queued job, and reopening does not restore local file selections.

Reference File RequirementsNew in 5.17+

Requirement	Limit
Formats	PDF, PNG, and JPEG (.pdf, .png, .jpg, .jpeg), subject to the selected model's capabilities.
Number of files	Up to 5, processed in the order shown.
Combined upload size	Up to 10 MB total. Files must not be empty.
PDFs	Complete files without encryption or password protection.
Images	At most 20 megapixels, with neither side exceeding 10,000 pixels.
Generated output	Up to 20 pages and 200 fields.

Your server's upload/request limits and the AI provider's document, context, account, and quota limits may be lower. The output limits refer to the generated Freeform form; the provider separately controls which source documents it can process.

Integration Compatibility

SolspaceAI supports references without a separate provider key or model selection. For other providers, reference support depends on the configured model, not just the provider name. The dialog enables attachments only when the selected integration and model report support for them.

Integration	Reference support
SolspaceAI	PDF, PNG, and JPEG using the existing authorized integration and credit balance. The hosted service selects the model.
OpenAI	PDF, PNG, and JPEG with recognized document/vision-capable models.
Anthropic	PDF, PNG, and JPEG with compatible Claude models. The original Claude 3 Haiku, Sonnet, and Opus models accept images only.
Gemini	PDF, PNG, and JPEG with recognized compatible Gemini models.
xAI	Text-based form generation. Reference uploads are not currently enabled for this integration.

Text-only models, specialized audio or image-generation models, and unrecognized/custom model identifiers may not enable attachments. Even when Freeform recognizes a model, your provider account must support the requested file type and document size. For providers with a configurable model, edit the integration to change it, then reopen Create with AI.

Dropdowns in Fillable PDFs

For supported fillable PDFs, Freeform reads embedded dropdown and multiple-select definitions, including choices hidden when the menu is closed. These definitions help every compatible provider recognize choice fields. When the AI matches a field to its source definition, Freeform preserves its choice type, option order, display labels, and separate export values. You can use additional instructions to request different field types or choices.

Images and flattened PDFs rely on visual recognition. Embedded-field extraction currently supports standard PDF cross-reference tables; compressed object/cross-reference streams, XFA forms, and unusually complex definitions fall back to visual recognition. A recognized dropdown with no recoverable choices may have an empty option list for you to complete. Always review the generated fields and choices against the source.

Background Generation

Generation runs through Craft's queue, so the upload request does not wait for the AI response or for the form to save. Freeform checks progress and reconnects to the same request if the initial response is lost, rather than automatically starting another generation.

Craft's normal control-panel queue runner is triggered when automatic queue processing is enabled. If generation stays queued, check Craft → Utilities → Queue Manager. For local development, including Herd, run the following from your Craft project directory in another terminal:

php craft queue/listen

Keep that worker running while generating. Production sites should use their usual supervised CLI queue worker. A CLI worker also avoids web-request time limits on the queue runner itself. Custom synchronous queue drivers are unsuitable. Web and worker processes must share Craft's private storage and security key so the worker can read the queued references.

The provider request still has a 120-second timeout, and provider or hosted-service limits apply independently. Fewer reference pages or a faster compatible model can help with those limits.

If progress cannot be confirmed, use Check progress and inspect the Forms list and Queue Manager before choosing Start a new request. Starting a new request does not cancel the previous job. Freeform retries status checks, but does not automatically repeat AI provider calls or regenerate a form when an interrupted job is retried.

Review the Generated Form

AI attempts to preserve labels, choices, required indicators, headings, page order, and rows of up to four fields. Headings and larger fields use their own rows. The result is a starting point that you can edit in Layout & Pages.

• Check field types, labels, choices, required settings, dates, and page/column layout against the source.
• Review copied text and remove any filled-in answers or personal details. The generator is instructed to omit completed answers and signatures, and generated default answers are cleared.
• Configure formatting, branding, logos, notifications, integrations, conditional rules, and calculations separately.
• Use Preview to check presentation and flow, then submit the actual embedded form on your site to verify validation and behavior.

The generator does not reproduce the document's exact appearance. Clear scans and screenshots give it more useful information; complex forms may work better when recreated in smaller sections.

Known provider responses cut short by output limits are rejected before saving, even if they contain valid JSON. Failed saves also attempt to clean up the newly created form. A forcibly stopped worker or database schema changes can still leave work that needs review; check the Forms list before generating again. Earlier partial forms are not automatically repaired.

Reference Files and Data Handling

References are sent to the selected AI provider using your integration's existing credentials. Use files appropriate for that provider's data-handling policies.

To support background generation, Freeform temporarily stores the prompt and reference data encrypted with Craft's security key in private storage/runtime/freeform-ai-generation files. No Craft assets are created. Queue payloads and browser session storage contain only opaque request identifiers. Only the authenticated user who started generation can check its status, and that user's permissions and site access are rechecked by the worker.

Reference inputs are deleted after normal completion or failure. Unstarted requests expire after 30 minutes. Abandoned encrypted inputs and status files older than one hour are removed on later generation starts or during Craft garbage collection; those cleanup processes must run to remove them. If generation fails, selected browser files remain available while the dialog stays open.

Local PDF extraction reads choice definitions without executing PDF scripts, actions, or external resources. It does not extract selected/default answers, but the original attachment is still sent to the provider, including any answers it contains. Use a blank copy when those details should not be shared.

Troubleshooting

• Attachments are unavailable: choose an integration and configured model that support references. You can still generate from a text prompt.
• The selected model cannot read a file: remove the incompatible file or choose a compatible integration. For example, an original Claude 3 image-only model cannot process a PDF.
• Upload fails: check the file limits above, PHP's upload_max_filesize, post_max_size, and max_file_uploads, and any proxy/request limits.
• PDF is rejected: attach a complete, unencrypted copy without password protection.
• No usable fields are found: use a clearer reference, attach a smaller section, or add instructions describing the form.
• Dropdowns become text fields or have missing choices: check whether the PDF has supported embedded choice fields. For flattened PDFs and images, include visible choices in the reference or describe them in the instructions. Review and complete the generated options manually where needed.
• Generation stays queued: check Queue Manager and start an asynchronous queue worker as described under Background Generation.
• A gateway error appears or progress stops: reopen the dialog in the same browser tab and use Check progress. Inspect the Forms list and Queue Manager before starting another request. A CLI worker can avoid nginx/PHP-FPM limits on web-based queue processing; AI provider limits still apply.
• The response reaches an output limit: generate fewer pages or a smaller section. Freeform rejects known truncated responses before saving; still review successful forms for omitted fields.
• Provider request fails: check the integration's authorization, configured model, account access, quotas, and document limits before retrying.