Higgsfield Websites

Skill: FNF SDK

Use this when the task touches @higgsfield/fnf: generation jobs, media upload, profile/workspace data, adapters, observability, or server-side job submission.

Before coding, read:

• app/packages/fnf/ai/AGENTS.md

• references/auth.md

Template Rules

• Adapter location: @higgsfield/fnf ships the SDK core, the backend ports, and exactly ONE bundled adapter — createWorkflowPlatformAdapter, at the @higgsfield/fnf/workflow-platform subpath (implementation: app/packages/fnf/src/workflow-platform/). That is the only adapter generated websites use, so the vendored fnf package is self-sufficient. The old @higgsfield/fnf/adapters subpath NO LONGER EXISTS — importing it is a build error. All other adapters (fnf-web, dev, apps-marketplace, memory) live in the separate @higgsfield/fnf-adapters package, which generated websites must not use.

• Keep fnf API calls server-side: createServerFn or *.server.ts.

• Do not call fnf from browser components.

• An SDK website is a real END-TO-END product, never a mock. It MUST have a real backend (server functions/routes) AND real persistence: opt into D1 ("db": true in app/app.manifest.json) and store the app's own product state — saved/favorited generations, collections, projects, prompt presets, share records, in-app user data. fnf stays the source of truth for the generations themselves; D1 is your product layer on top of it. In-memory arrays, module-level state, localStorage-as-database, hardcoded fixtures, and memory/mock adapters shipped as the product are NOT a backend — they are bugs.

• A real generation website is never "just a form." If the prompt mentions using a Higgsfield model, SDK, generation, media upload, or model settings, the website must include auth, profile/credits/workspace display, submit/cost/media server operations, and a generation feed/history by default.

• If the website has any real SDK-backed generation/media/profile/credits feature, it must require auth. Implement /api/user, signed-out UI, login/logout, and a server-side auth check before each SDK operation.

• Do not use app-local/in-app auth as the guard for Higgsfield SDK operations. In-app auth can coexist for product users, but SDK submit/upload/profile/ credits/feed routes must still be protected by Higgsfield auth through /api/user and server-side https://fnf.internal/user.

• Browser auth/user UI calls /api/user; that route proxies https://fnf.internal/user server-side. Do not call fnf.internal from the browser.

• Generated websites must use createWorkflowPlatformAdapter with baseUrl: 'https://fnf.internal' from server code. Do not use env-controlled backend URL selectors, public fnf URLs, dev fnf URLs, apps-marketplace, or direct product routes in generated websites.

• This strict rule is for Supercomputer/template-generated websites. If the user explicitly asks for a separate SDK consumer with another approved endpoint, use that host's adapter or custom SDK backend ports instead of forcing fnf.internal.

• Do not expose service secrets, dev user ids, bearer tokens, media upload URLs, prompts, or raw backend bodies to the client.

• Register only the job models the website uses.

• Upload/resolve media before submit.

• Display credits are already normalized when using client.cost(input).credits or profile.getCredits(). Raw wallet fields from getWallet() are credit-cents; divide by 100 or use getCredits() for UI.

• Observability is safe metadata only. Never emit prompts, params, headers, tokens, URLs, filenames, emails, workspace names, or raw bodies.

Mandatory Generation Website Checklist

For prompts like "create a Nano Banana generation app", "build a Seedance form", "make an image/video generator", or anything equivalent, deliver all of this:

• GET /api/user route that proxies https://fnf.internal/user server-side.

• Signed-out state with a Quanta sign-in button to /__auth/login?return=<current path>.

• Logout action to /__auth/logout?return=/.

• Server-side auth guard before every SDK submit, upload, cost, feed, profile, credits, workspace, Elements, character-training, realtime edit/finalize, and saved-style operation.

• Profile tab/panel showing safe user fields, current workspace, and display credits from profile APIs.

• Model form with validated settings for the requested model.

• Cost preview using the SDK cost path when supported by the chosen model.

• Submission confirmation gate: a browser confirmation modal (model, settings summary, cost preview) BEFORE calling the generate route, plus the adapter confirm option wired server-side (see "Submission Confirmation Gate" below). A declined confirmation surfaces as the typed confirmation_rejected error and renders as a cancelled state, not a failure.

• Media upload route using multipart FormData when the model accepts media.

• Submit route/server function using createJobClient and registered jobs.

• Feed/history panel using SDK list/get/getSet data so the user can see queued, running, completed, and failed generations after submit.

• Real persistence in D1 for the app's own product state (e.g. saved/favorited generations, collections, projects, prompt presets, share records): "db": true in app/app.manifest.json plus an additive app/migrations/000N_*.sql. Do not fake persistence with in-memory or localStorage state.

• Poll submitted generations until terminal status; do not stop after the submit response if jobs are still queued/running.

• Render actual SDK result media in the feed/history. Use HiggsfieldGenerationCard and selectGenerationMedia, or equivalent logic using SDK selectors (getPreviewUrl, getRawUrl, getMediaType, getJobPhase, hasResult, isTerminalJobStatus).

• Show prompt, model, status, created time, and failure reason where available. Do not render completed jobs as blank cards with only status/id text.

• Keep one truthful export-format contract for every media type. Preserve and label provider-native output, or carry a supported model format field through preview, confirmation, submit, and download. Never fake PNG/JPEG/WebP consistency by renaming a URL or filename.

• Request/debug logs on server SDK routes: method, logical operation/path, response status, SDK error code/status/message. Never log prompts, raw params, headers, tokens, cookies, upload URLs, filenames, emails, workspace names, or file bytes.

Omission is a bug. The ONLY exception is when the user EXPLICITLY asks for an offline/mock demo (memory adapters, no network) — never choose a mock as the default; the default is a real, end-to-end app with a real backend and D1.

Output and download format contract

Choose the app's public export behavior once and apply it to every submit and download path:

• If the registered model's documented schema exposes an output-format field, offer only its supported values, choose one app default, and carry that field in the same canonical SDK input used by getWirePreview, confirmation, and submit. Do not invent a universal outputFormat key; use the exact current job-schema field.

• Treat optimized previews as display derivatives only. getPreviewUrl() may legitimately resolve to WebP or another optimized encoding even when the raw/export asset is PNG or JPEG. Use getRawUrl() for open/download, or the URL of bytes the app genuinely transcoded server-side.

• Make bytes, MIME type, and filename agree. Derive the extension and Content-Type from trusted result metadata or the fetched raw response; a download proxy must forward/set matching Content-Type and Content-Disposition. Never save WebP bytes under .png, or infer format from the preview URL's suffix.

• If the product promises a fixed format that the model cannot guarantee, transcode the raw bytes in a real server-side path that supports the codec (a container when Worker-native capabilities are insufficient). If that path is not built, label and preserve the provider-native format instead of advertising a false fixed format.

For protected app-local downloads inside the Higgsfield iframe, also follow references/auth.md → "Authenticated File Downloads". A direct raw link is valid only when it is public or a self-contained signed URL requiring no session.

Elements and custom-reference character training

Use these capabilities when an app needs reusable user assets or a consistent trained subject. Keep the concepts distinct:

• Elements are the signed-in user's reusable asset library. A Character is one kind of Element. Browse Elements with createReferenceClient from @higgsfield/fnf/references; do not call them all characters and do not invent app-local copies of the library.

• Character training is a separate multi-image custom-reference operation. Use createCharacterClient from @higgsfield/fnf/characters. Training creates a processing Character Element and returns a custom-reference id.

• Generation uses that custom-reference id as settings.customReferenceId on a compatible Soul job. Presets are not part of this flow.

All calls stay server-side after the Higgsfield auth guard and reuse the same createWorkflowPlatformAdapter({ baseUrl: 'https://fnf.internal' }):

import { createCharacterClient } from '@higgsfield/fnf/characters'
import { createJobClient } from '@higgsfield/fnf/client'
import { soulV2Image } from '@higgsfield/fnf/jobs'
import { createReferenceClient } from '@higgsfield/fnf/references'
import { createWorkflowPlatformAdapter } from '@higgsfield/fnf/workflow-platform'

const adapter = createWorkflowPlatformAdapter({
  baseUrl: 'https://fnf.internal',
  confirm: async () => confirmationToken,
})

const elements = createReferenceClient({ adapter })
const characters = createCharacterClient({ adapter })
const jobs = createJobClient({ adapter, jobs: [soulV2Image] })

const library = await elements.list({ category: 'character', size: 50 })

// images are MediaRef values returned by media.upload(...) or compatible
// image job refs. Upload browser Files with multipart FormData first.
const pending = await characters.create({
  name: 'My character',
  type: 'soul_2',
  images,
})
const character = await characters.wait(pending)
if (character.status === 'failed')
  throw new Error(character.failReason ?? 'Character training failed')

const result = await jobs.submit({
  model: 'text2image_soul_v2',
  prompt: { instruction: 'Candid flash photo at a late-night diner' },
  settings: {
    customReferenceId: character.id,
    aspectRatio: '3:4',
    batchSize: 4,
  },
})

Character contract:

• Supported training types are soul, soul_2 (default), and soul_cinematic. Expose the requested types; do not hard-code a /soul-v2 transport or reimplement one backend variant.

• Training accepts 1–100 image references. soul accepts uploaded media_input refs only; soul_2 and soul_cinematic also accept compatible image job refs whose type ends in _job.

• Poll characters.get(id) or characters.wait(character) until completed or failed. On completion, refresh the Elements list; the result may also expose elementId.

• Existing Character Elements expose reference.characterId; use that value as customReferenceId. The Element id and custom-reference character id are different ids.

• references.list({ cursor, size, category }), references.get(elementId), characters.create(...), and characters.get(characterId) are the public SDK operations. Never hand-write /reference-elements or /custom-references fetches.

• Do not add a custom per-image/per-job approval workaround around character training. Reuse platform auth, upload, submission, and approval infrastructure; the normal confirmation gate still applies to the Soul generation submission.

A complete Elements-and-character flow includes auth/profile/credits, an existing Elements picker, multipart multi-image upload, create + poll character states, Elements refresh, Soul generation using customReferenceId, the normal confirmation/cost flow, generation polling, and history/result rendering.

Stateful realtime image editing and saved custom styles

Use the realtime client when an app needs successive image edits in one chain or user-level saved styles:

import {
  buildRealtimeChainEditRequest,
  createRealtimeClient,
  type RealtimeChainEditInput,
} from '@higgsfield/fnf/realtime'
import { createWorkflowPlatformAdapter } from '@higgsfield/fnf/workflow-platform'

const adapter = createWorkflowPlatformAdapter({ baseUrl: 'https://fnf.internal' })
const realtime = createRealtimeClient({ adapter, jobAdapter: adapter })

const input: RealtimeChainEditInput = {
  params: {
    prompt: 'Turn this into a candid editorial portrait',
    resolution: '1k',
    aspectRatio: '1:1',
    images, // explicit MediaRef/image-job refs; at most four
  },
}
const cost = await realtime.estimateChainCost({
  resolution: input.params.resolution,
  aspectRatio: input.params.aspectRatio,
})
// Browser: request approval for the exact validated wire.
const wire = buildRealtimeChainEditRequest(input)
const confirmationToken = await window.hf.requestGeneration(
  'flux_klein_realtime',
  wire,
  { credits: cost.credits },
)
// Authenticated server function: submit the same input with its opaque token.
const edit = await realtime.editChain(input, { confirmationToken })
const generation = await realtime.pollEditJob(edit.jobId)

// Continue by passing edit.chainId and a new explicit image set.
await realtime.finalizeChain({ chainId: edit.chainId })

The confirmation call runs in the browser through window.hf.requestGeneration; the client creation, edit, polling, finalize, and style calls stay behind authenticated server functions. Send the opaque token and the exact same input to the server; never log it. If one action launches several independent edits, build every wire request first and use the existing batch confirmation form, matching returned tokens by index. Every editChain call is billable and intentionally not retried.

Realtime contract:

• Omit chainId to start; pass the returned chainId to continue. Previous outputs are not appended automatically: every attempt supplies its own images array of up to four uploaded media_input or image-job refs.

• Provide exactly one of prompt or structured settings. Structured settings may select a saved style with style: 'custom' and customStyleId.

• Use getEditJob / pollEditJob and normal Generation selectors to render the result. Call finalizeChain when the editing session ends.

• Saved styles are authenticated user-level data. Manage them only through listCustomStyles, createCustomStyle, updateCustomStyle, and deleteCustomStyle. A style reference mediaId must be an upload or job the user/app may access; a listed Element's metadata is not a raw-media picker.

• Never hand-write /realtime/* requests or invent a separate approval mechanism. Reuse the platform adapter, auth guard, multipart upload path, and confirmation infrastructure.

Common Imports

import { createJobClient } from '@higgsfield/fnf/client'
import { createMediaClient } from '@higgsfield/fnf/media'
import { createProfileClient } from '@higgsfield/fnf/profile'
import { createWorkflowPlatformAdapter } from '@higgsfield/fnf/workflow-platform'
import { nanoBanana2, seedance2_0 } from '@higgsfield/fnf/jobs'

Server Pattern

Create the adapter inside server-only code after auth has been checked.

const auth = await requireCurrentUser()
if (!auth.ok) {
  return new Response(JSON.stringify(auth.body), {
    status: auth.status,
    headers: { 'content-type': 'application/json' },
  })
}

Then create SDK clients with the fnf.internal logical-operation adapter:

const FNF_INTERNAL_BASE_URL = 'https://fnf.internal'

const adapter = createWorkflowPlatformAdapter({
  baseUrl: FNF_INTERNAL_BASE_URL,
  observability,
})

const jobs = createJobClient({ adapter, jobs: [seedance2_0, nanoBanana2] })
const media = createMediaClient({ mediaAdapter: adapter })
const profile = createProfileClient({ profileAdapter: adapter })

Generated websites use fnf.internal only:

const adapter = createWorkflowPlatformAdapter({
  baseUrl: 'https://fnf.internal',
  observability,
})

Do not pass getToken. Do not send Authorization. The platform attaches identity automatically for server-side calls to https://fnf.internal.

This adapter sends SDK operations only under the fnf.internal logical route families /user, /workspaces/*, and /jobs/*. The platform behind fnf.internal decides final internal routing.

Do not add model-specific route logic in website code. The SDK builds validated wire params, fnf.internal resolves final endpoints, and the website handles only safe request/response state.

Generated websites must never use:

process.env.FNF_BASE_URL
const backendUrl = process.env.SOME_BACKEND_URL
createWorkflowPlatformAdapter({ baseUrl: backendUrl })
createFnfWebAdapter({ baseUrl: '...' })
createDevFnfWebAdapter(...)
createAppsMarketplaceAdapter(...)
fetch('https://fnf.internal/jobs') // hand-written request; use the SDK adapter

fnf.internal Method Contract

Generated websites must not decide fnf.internal HTTP methods themselves. Use SDK clients, and let createWorkflowPlatformAdapter send the correct operation:

If the browser calls an app-local route for generation, that app route must be a mutation route such as POST /api/generate; it must not be GET. The route then checks auth server-side and calls jobs.submit(...). Do not forward browser requests directly to fnf.internal, /jobs, /jobs/v2/*, or /api/user.

For TanStack server functions, use createServerFn({ method: "POST" }) for submit, cost, media upload, workspace switch, and other write-like SDK operations. Use GET only for pure read functions. A 405 / "Method Not Allowed" on generation almost always means the generated website used a GET route/function for a submit/cost/media operation, or tried to call a fnf.internal write operation through a query string instead of letting the SDK use the static POST route.

Strict Media Upload Contract

Binary files must never cross a JSON server-function boundary. Do not pass File, Blob, ArrayBuffer, Uint8Array, base64 strings, or arrays of bytes inside createServerFn input or JSON request bodies. This causes stack overflows, huge payloads, broken serialization, or unusable object-shaped bytes.

Use one of these two patterns:

1. Browser uploads to an app-local POST /api/media/upload route with FormData.

2. Browser uses useAttachments only when the provided media client has a safe browser-capable upload path. For server-only fnf.internal/auth flows, prefer the FormData route.

Then generation submits only the returned MediaRef:

File in browser
  -> POST multipart FormData /api/media/upload
  -> server auth guard
  -> media.upload({ source: bytes, ... })
  -> returns MediaRef
  -> POST JSON /api/generate with prompt/settings/MediaRef only
  -> server auth guard
  -> jobs.submit(...)

Client upload example:

const form = new FormData()
form.append('file', file)

const response = await fetch('/api/media/upload', {
  method: 'POST',
  body: form,
})

const upload = await response.json()
if (!upload.ok)
  throw new Error(upload.error?.code ?? 'upload_failed')

Do not set the content-type header manually for FormData; the browser must add the multipart boundary.

Server upload route example:

import { createFileRoute } from '@tanstack/react-router'
import { createMediaClient } from '@higgsfield/fnf/media'

export const Route = createFileRoute('/api/media/upload')({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const auth = await requireCurrentUser()
        if (!auth.ok) {
          return Response.json(
            { ok: false, error: { code: 'unauthorized', status: auth.status } },
            { status: auth.status },
          )
        }

        const form = await request.formData()
        const file = form.get('file')
        if (!(file instanceof File)) {
          return Response.json(
            { ok: false, error: { code: 'missing_file' } },
            { status: 400 },
          )
        }

        console.info('[api/media/upload] file', {
          contentType: file.type,
          size: file.size,
        })

        const bytes = new Uint8Array(await file.arrayBuffer())
        const media = createMediaClient({ mediaAdapter: adapter })
        const result = await media.upload({
          source: bytes,
          filename: 'upload',
          contentType: file.type,
          type: 'image',
          forceIpCheck: true,
        })

        return Response.json({ ok: true, ref: result.ref })
      },
    },
  },
})

Generation route input must look like this:

{
  prompt: string
  settings: { aspectRatio: '3:4', resolution: '1k', batchSize: 1 }
  media?: { image?: MediaRef }
}

Do not include file, blob, bytes, arrayBuffer, base64, or raw data:image/... values in generation input. If upload fails with Maximum call stack size exceeded, the website almost certainly tried to serialize binary through JSON or used String.fromCharCode(...bytes) on a large file.

Job Client Pattern

Only call the job client after the server auth guard succeeds.

Register exactly the models the website exposes:

const jobs = createJobClient({
  adapter,
  jobs: [seedance2_0, nanoBanana2],
})

Use public camelCase settings:

await jobs.submit({
  model: 'seedance_2_0',
  prompt: { instruction: prompt },
  settings: {
    mode: 'std',
    duration: 5,
    aspectRatio: '16:9',
    resolution: '720p',
    batchSize: 1,
  },
})

Never send snake_case settings from UI code. The SDK maps aspectRatio to aspect_ratio, batchSize to batch_size, and similar wire fields through job schemas.

Server-function submit example:

import { createServerFn } from '@tanstack/react-start'
import { z } from 'zod'
import { createJobClient } from '@higgsfield/fnf/client'
import { createWorkflowPlatformAdapter } from '@higgsfield/fnf/workflow-platform'
import { nanoBanana2 } from '@higgsfield/fnf/jobs'

export const generate = createServerFn({ method: 'POST' })
  .inputValidator(z.object({
    prompt: z.string().min(1),
    // set by the browser confirmation modal — see "Submission Confirmation Gate"
    confirmed: z.literal(true),
  }))
  .handler(async ({ data }) => {
    const auth = await requireCurrentUser()
    if (!auth.ok) {
      return {
        ok: false as const,
        code: 'unauthorized',
        status: auth.status,
      }
    }

    const adapter = createWorkflowPlatformAdapter({
      baseUrl: 'https://fnf.internal',
      confirm: async () => {
        if (!data.confirmed)
          throw new Error('user did not confirm the submission')
      },
    })

    const jobs = createJobClient({ adapter, jobs: [nanoBanana2] })
    const result = await jobs.submit({
      model: 'nano_banana_2',
      prompt: { instruction: data.prompt },
      settings: { aspectRatio: '3:4', resolution: '1k', batchSize: 1 },
    })

    return { ok: true as const, result }
  })

Do not use createServerFn({ method: "GET" }) or a GET server route for generation. Generation is a mutation even when the form has no uploaded file.

LLM chat / text — createLlmClient (NOT a job)

Chat/text generation is separate from the media jobs registry. Worker-side ONLY, zero-token (no getToken/userId — the platform attaches the visitor's identity and bills their credits):

import { createLlmClient } from '@higgsfield/fnf'
const llm = createLlmClient({ baseUrl: 'https://fnf.internal/llm' })

const [model] = await llm.listModels()
if (!model) throw new Error('No LLM models are currently available')

const res = await llm.complete({
  model,
  messages: [{ role: 'user', content: '…' }],
})
// llm.stream(...) yields OpenAI-shape SSE deltas; tool-calling supported
// (LlmToolDef / LlmToolCall). In React: FnfProvider's `llm` prop + useFnfLlmClient().

Model availability is runtime gateway configuration. Never hardcode a catalog or claim that one model is always available. Call listModels() server-side, use the exact returned id, and handle an empty list. Model pickers may receive those ids through an authenticated app-local server function or route; if a previously selected id disappears, refresh the list and show that it is no longer available instead of silently substituting another model.

App-only. Text generation is generation → type: "app" (Sign in with Higgsfield, visitor credits). NEVER on a type: "website" build, and never a "bring your own LLM key" path.

Submission Confirmation Gate

The SDK requires hosts that submit generations on behalf of a user to implement a confirmation gate. Every generation adapter factory accepts a confirm option (ConfirmSubmit from @higgsfield/fnf); jobs.submit calls it once per submission — after validation, before any network call. Resolve to proceed (a resolved string rides the create request as confirmation_token); reject/throw to abort with the typed confirmation_rejected error.

In a generated website the submit runs server-side, so split the gate across the boundary:

1. Browser: before calling the generate server function, show a Quanta confirmation modal with the model, a settings summary, and the cost preview. Only call the generate function after the user confirms; send confirmed: true (or an app-minted confirmation token) in the JSON input.

2. Server: wire the adapter's confirm to that input — resolve when the browser confirmed, throw when it did not:

const adapter = createWorkflowPlatformAdapter({
  baseUrl: 'https://fnf.internal',
  // Runs during jobs.submit, after validation, before any network call.
  confirm: async () => {
    if (!data.confirmed)
      throw new Error('user did not confirm the submission')
    return data.confirmationToken // optional; sent as confirmation_token
  },
})

Rules:

• Never auto-confirm (confirm: async () => {} with no browser modal defeats the gate). The modal is mandatory for real generation websites.

• Branch on error.code === 'confirmation_rejected' and render it as a user-cancelled state (quiet), not an error toast.

• The confirmation token is a token: never log it or emit it through observability.

Generation Result Rendering Contract

Every real generation website must show submitted and historical generations with real media previews. Use the template helpers by default:

import { HiggsfieldGenerationCard } from "@/components/higgsfield-generation-card"
import { selectGenerationMedia } from "@/lib/higgsfield-generation-results"

The helper uses the SDK read model:

• image cards render getPreviewUrl(generation) for the optimized preview and getRawUrl(generation) for open/download.

• video cards render getRawUrl(generation) as the playable <video src> and generation.results.thumbnailUrl / getPreviewUrl(generation) as the poster when the preview is an image.

• pending/queued/in-progress/ip-detect states render progress UI.

• failed/nsfw/canceled/ip-detected states render the status/failure reason.

• completed jobs with no result URL render "Preview unavailable" and keep a refresh/get action available.

When writing custom cards, keep the same selector contract:

import {
  getJobPhase,
  getMediaType,
  getPreviewUrl,
  getRawUrl,
  hasResult,
  isTerminalJobStatus,
} from "@higgsfield/fnf/client"

Never inspect raw backend results.raw.url objects in website UI. The SDK adapter normalizes product/WFP responses into Generation.results; render that model. Never log prompts or raw media URLs. Displaying the signed-in user's prompt in their own UI is allowed.

Model Catalog Snapshot

Use the package guide as source of truth, but common generated-website choices are:

• Images: soulV2Image, soulCinemaImage, gptImage2, seedreamV4_5, nanoBanana2, nanoBananaFlash, recraftV41Image.

• Video: seedance2_0, kling3_0, kling3MotionControl, happyHorse, grokImagine, grokImagineV15, veo3_1Lite, wan27.

• Upscale: topazImageUpscale, topazImageGenerativeUpscale, nanoBanana2Upscale, topazVideoUpscale, higgsfieldVideoUpscale, soraEnhanceVideo, bytedanceVideoUpscale.

Import only the entries the screen needs. The jobs: [...] array is the source of model autocomplete and media-role narrowing.

Media Pattern

Use createMediaClient({ mediaAdapter: adapter }) server-side after auth, or behind a safe client boundary that still reaches a server auth guard. Upload first, then submit the returned MediaRef:

const upload = await media.upload({
  source: fileBytes,
  filename: 'input.png',
  type: 'image',
  forceIpCheck: true,
})

await jobs.submit({
  model: 'nano_banana_2',
  media: { image: upload.ref },
  prompt: { instruction: prompt },
})

Attach/resolve media metadata before submit when local validation depends on dimensions or duration. Unknown metadata is allowed locally; backend remains authoritative.

Allowed media.upload({ source }) values are only Blob, ArrayBuffer, Uint8Array, or { read: async () => Blob | ArrayBuffer | Uint8Array }. The SDK throws invalid_media_source for JSON-shaped objects so broken upload plumbing fails clearly before presign/transfer.

Profile And Workspace

Use the profile domain for account/workspace panels:

const snapshot = await profile.getSnapshot()
const credits = await profile.getCredits({ includeOnDemand: true })
await profile.switchWorkspace({ workspaceId })

Workspace switching updates backend context only. The website still owns routing, session metadata, adapter header state, and cache invalidation.

Do not use profile.getUser() directly in browser components for auth gating. For browser UI, use /api/user from references/auth.md. Use the SDK profile client server-side when the website is already performing SDK-backed account, workspace, wallet, or credit operations.

Credit display rule:

• profile.getWallet() returns raw backend credit-cent values.

• profile.getCredits() returns display credits.

• profile.getCredits() returns a ProfileCredits object, not a number. Use credits?.totalAvailableCredits, credits?.availableCredits, or snapshot.credits?.totalAvailableCredits in UI.

• jobs.cost(input).credits returns display credits.

• Do not show raw wallet values directly in UI.

Marketplace / Service Adapters Are Not For Generated Websites

Some fnf snapshots include createAppsMarketplaceAdapter. It is server-side only, defaults to the dev apps-marketplace backend for now, and is for SDK smoke tests or trusted service experiments only. Generated websites must not use it. Generated websites use createWorkflowPlatformAdapter({ baseUrl: 'https://fnf.internal' }) exclusively.

Job UI Pattern

For a generated website UI:

1. Build the form with Quanta components.

2. Load /api/user before enabling SDK-backed controls.

3. If signed out, show sign-in UI and disable/hide generation, upload, cost, feed/history, profile, workspace, and credit actions.

4. Confirm before submit: show the confirmation modal (model + cost) and call the generate function only after the user confirms; wire the adapter confirm option server-side (see "Submission Confirmation Gate").

5. Keep submit/cost/profile/media calls in server functions or safe app-local server-only modules.

6. Re-check auth inside each server function before calling SDK clients.

7. Return only safe data to the browser: generation ids, statuses, display credits, and sanitized errors.

8. Use safeSubmit/typed error codes when crossing worker/iframe boundaries.

9. Show validation, cost, upload state, running state, terminal state, cancelled-confirmation state (confirmation_rejected), and typed errors as real UI states.

Do not build anonymous real generation. The only allowed anonymous SDK-looking flow is a mock/offline demo the user EXPLICITLY asked for (memory adapters, no network requests) — never the default.

Troubleshooting Generation 405

If sign-in works but generation fails with Method Not Allowed:

1. Confirm the app-local generation function/route is POST, not GET.

2. Confirm the code calls jobs.submit(...) or jobs.cost(...) through the SDK, not hand-written fetch('/jobs?...').

3. Confirm createWorkflowPlatformAdapter({ baseUrl }) uses exactly https://fnf.internal, not the deployed website URL, /api/user, a public fnf URL, a dev fnf URL, or a model-specific fnf route.

4. Confirm the server handler re-checks https://fnf.internal/user before SDK calls, then creates the adapter/client inside the server handler.

5. Confirm reads use SDK-backed GET routes such as /jobs, /jobs/{id}, or /jobs/sets/{id}, while submit/cost/cancel/media writes use SDK-backed POST routes such as /jobs/submit, /jobs/cost, and /jobs/media/presign. Do not send submit/cost/media operations through GET query parameters.

If upload fails with Maximum call stack size exceeded:

1. Search for String.fromCharCode(..., base64 conversion, JSON.stringify(file), Array.from(bytes), or passing File/Blob/ArrayBuffer to createServerFn input.

2. Replace that flow with FormData POST to /api/media/upload.

3. Return only { ref: MediaRef } from upload.

4. Send only that MediaRef in generation JSON.

5. Add logs for file size and contentType, but never file bytes, upload URL, token, raw prompt, or raw backend body.

Observability

SDK observability is a safe metadata callback. It is not product analytics by default and it must not leak prompts, params, headers, tokens, URLs, filenames, emails, workspace names, or raw bodies.

Allowed metadata examples: model id, operation, status, duration, safe job id, safe media id, media type, credit estimate, and error code.

Pass observability to the adapter as well as clients when debugging transport problems:

const adapter = createWorkflowPlatformAdapter({
  baseUrl: 'https://fnf.internal',
  observability,
})

const jobs = createJobClient({ adapter, jobs: [nanoBanana2], observability })
const media = createMediaClient({ mediaAdapter: adapter, observability })

Without adapter observability you may see fnf.job.submit fail but not the underlying fnf.transport.request method/path/status.