1
Send the prompt to your agent
# Task: build an app on the Higgsfield API.
Higgsfield is a generative media API. It serves image and video models (Seedance, Kling, Soul, Flux, Wan and more) behind one REST interface. Create and manage API keys at [open.higgsfield.ai](https://open.higgsfield.ai/api-keys).
Use **Connect API key** for the initial connection action. The modal should say: **“Paste the API key copied from open.higgsfield.ai. Paste it as-is.”** Collect the complete copied key in one password field; do not ask users to split or assemble credentials or require a colon in the UI. Preserve the `Key` authorization scheme for server-side REST requests.
## How the API works
1. **Submit.** `POST https://api.higgsfield.ai/<model-path>` with a JSON body.
- Headers: `Authorization: Key <api-key>` and `Content-Type: application/json`. `<api-key>` means the complete copied credential, without an added `Key` prefix inside the value.
- The response contains `request_id`, `status_url` and `cancel_url`.
2. **Poll.** `GET https://api.higgsfield.ai/requests/<request_id>/status` until the status is terminal: `completed`, `failed`, `nsfw` or `canceled`.
- `completed` returns media URLs: `images[].url` or `video.url`.
3. **Cancel.** `POST https://api.higgsfield.ai/requests/<request_id>/cancel` for requests eligible for cancellation. Cancel must reach the API; stopping polling alone does not cancel a generation.
4. **Upload references.** Request a signed upload URL on the server with `POST https://api.higgsfield.ai/files/generate-upload-url` and `{"content_type": "image/png"}`, using the same saved API key.
- The response has `upload_url`, `upload_headers` and `public_url`.
- The browser PUTs the file to `upload_url` with every returned upload header and credentials omitted. Do not add the API authorization header to this storage request.
- Record and use `public_url` only after the PUT succeeds. Never log signed upload URLs. No separate storage token is needed.
Example (text-to-video; verify the endpoint and schema before using it). Here `HF_API_KEY` is a server-side environment variable containing the complete copied API key:
```bash
curl -X POST https://api.higgsfield.ai/bytedance/seedance-2.0/text-to-video \
-H "Authorization: Key ${HF_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"prompt":"A cinematic tracking shot along a sunlit coastal road","resolution":"720p","generate_audio":true,"duration":5,"aspect_ratio":"16:9"}'
```
## Verify the documentation first
Treat the API overview and example above as starting points, not verified current contracts.
1. Read the [documentation index](https://docs.higgsfield.ai/docs/llms.txt). Follow the authentication, SDK, polling, webhook, file-upload and error-handling documentation relevant to the integration.
2. Discover models at [open.higgsfield.ai/explore](https://open.higgsfield.ai/explore). Use `open.higgsfield.ai` for the platform website and `https://api.higgsfield.ai` for REST requests, even if a documentation page still links to an older website domain.
3. Select the model and operation, then open its API documentation.
4. Follow the model-specific `llms.txt` link when available. Read the endpoint and Input JSON Schema, including required fields, supported parameters and limits.
5. Use links from the documentation; never invent model-documentation URLs. Treat the shared OpenAPI file as supplementary, not the authoritative model catalog.
6. If a schema cannot be verified or sources conflict, report the specific uncertainty and continue work that does not depend on it. Do not invent a new mapping or silently substitute models or production/preview endpoints. Distinguish documented availability from access verified with my account.
7. **Keep every installed model available while verification is incomplete.** Missing documentation or lack of live API testing does not authorize filtering the catalog down to tested models. Report what is unverified; restrict the catalog only if I explicitly request a smaller set.
## Step 1: pick the path
- **No existing application:** go to Step 2A. Inspect the directory first; absence of `package.json` alone does not mean it is empty.
- **There is an existing app:** go to Step 2B.
Use the product brief and decisions I have already provided. Ask what the app should create only if that is still unclear.
## Step 2A: new app, start from the Higgsfield Studio template
1. From the parent directory, not inside a project, scaffold the template (this creates `<app-name>/`):
```bash
pnpm dlx shadcn@latest init -t next -n <app-name> --no-monorepo -y higgsfield-ai/app-templates/studio
```
2. Read `AGENTS.md`, `layouts/AGENTS.md` and `components/studio/AGENTS.md` in the generated app before changing it. They define the template's conventions and requirements.
3. Run `cd <app-name> && pnpm dev`, then open the local URL reported by the dev server, normally `http://localhost:3000`.
4. Reuse what the template already provides:
- A Next.js Studio UI.
- Submit, polling and cancel in `generation/`.
- Signed reference uploads through `app/api/upload/route.ts`.
- The full bundled model catalog in `generation/catalog/models/`.
- Model discovery with `pnpm dlx shadcn@latest list higgsfield-ai/app-templates` and model additions with `pnpm dlx shadcn@latest add higgsfield-ai/app-templates/<model>`.
5. Preserve all installed models during adaptation. `studio` includes the complete bundled catalog by default; use `studio-bare` or a model allowlist only if I explicitly request a smaller catalog. Check installed model files, the generated barrel, the public catalog export and picker filtering before concluding that models are missing. Let the existing sync script regenerate `generation/catalog/models.generated.ts`; never hand-edit it.
6. Preserve the default credential flow: each user clicks **Connect API key** in the sidebar and pastes the complete key copied from [open.higgsfield.ai](https://open.higgsfield.ai/api-keys). The server action stores it in an HTTP-only cookie, and authenticated platform requests stay on the server.
- Use **Manage API key** for the configured-key dialog, **Replace API key** for replacement and **Remove API key** for removal. The sidebar can show **API key saved** after saving; saving alone does not prove that the key is valid.
- Collect the key only in the key dialog. Do not persist it in localStorage or IndexedDB, expose it in client bundles, return it from server actions, or log it.
- If I explicitly want the app to run on my shared key, adapt the server credential reader to use a server-only `HF_API_KEY` containing the complete copied key. This is an optional adaptation, not the template's default configuration.
- For a shared-key app, save each `request_id` with the authenticated user or tenant who created it. Enforce ownership in status, results and cancel handlers; browser-local history is not an authorization system.
7. Verify the relevant model mappings and confirm the server-side `HF_API_BASE_URL` is `https://api.higgsfield.ai`. Keep the installed catalog intact while documenting any unverified mappings or account access.
8. Adapt the template to the requested product until the “Definition of done” in `AGENTS.md` is met. Replace placeholder presets, media and copy, and make every visible control perform its named action.
## Step 2B: existing app
1. Inspect the framework, backend or agent architecture, authentication, user/tenant model, file storage and background jobs. Read the repository's applicable instructions.
2. Explain briefly where Higgsfield fits. If the intended output is unclear, ask what users should create: images, animating uploaded images, or videos from prompts. If it is unclear whether I want an app feature or a tool for a coding agent, resolve that before making dependent changes.
3. Once the use case is clear, use the documented official SDK or direct REST requests, following the project's conventions:
- For REST, use `https://api.higgsfield.ai` and `Authorization: Key <api-key>` with the complete copied credential.
- Preserve an existing compatible server-side credential flow. When adding an app-owned credential flow, use a server-only `HF_API_KEY` and an empty placeholder in `.env.example`. For user-supplied keys, use the **Connect API key** wording and keep authenticated provider calls on the server.
- If using an SDK, follow its documented credential configuration rather than assuming it reads the REST example's environment variable.
- Never put credentials in client bundles, logs or committed files. Never send authenticated provider requests directly from the browser.
4. Store each `request_id` with its user or tenant, and check ownership before returning status or results or allowing cancellation.
5. Preserve existing installed models and user choices unless I explicitly request a smaller catalog. Report unverified support without silently hiding models.
## Step 3: both paths
- Validate inputs against the selected model's schema. Keep server-side validation and strict TypeScript intact.
- Show progress and failures. Handle missing or invalid keys, rate limits, polling backoff, timeouts and terminal states according to the current documentation. Keep failed and canceled runs visible to the user.
- Prevent accidental duplicate submissions in both the UI and server handling. Do not blindly retry a generation POST after an ambiguous timeout.
- Consider webhooks when the app has background processing, following the documented verification and delivery-handling requirements.
- Run relevant tests, typecheck, lint and build. In a fresh template, run dev or build once before typechecking so the model barrel is generated. Report environmental blockers and unverified live API behavior accurately.
- For Studio adaptations, verify that every installed model appears in its image/video picker, including models that were not exercised in live API tests. Check key entry, model switching, prompt-only generation, reference uploads, settings and cancellation as access permits.
- Tell me what changed, which environment variables or keys to set, how to try it, and what was not verified.
