AI

The AI surface has four areas: image generations (async records you poll), one-shot AI actions (synchronous request/response under /actions), the chat agent (conversations with tools, MCP servers, rules and skills), and prompt templates that power the image studio. Everything is charged from the user's wallet in credits (1 credit = 1 DZD) — see Billing & credits.

Template-focused AI (custom components, page edits, landing-page generation) is covered conceptually in Templates → AI; this page documents the HTTP surface. General request/response conventions live in API conventions.

Image generations

Async jobs: POST …/generate returns the record immediately with status: "pending" and the image is produced in the background. Poll GET /v1/image_generations/{id} until status is completed, published or failed (failure reason under configs.error).

generate accepts multipart form data: prompt, storeId, model (catalog id), aspectRatio, imageSize (1K / 2K / 4K), resolution (how reference images are processed), attachments (JSON array of image / store / product / audio refs — store and product ids are expanded into structured brand/product context server-side), an optional imageFile to edit, and per-model options (googleSearch, imageSearch, background, quality, outputFormat). At least one of prompt, image or reference attachments is required. A record that is still pending/processing answers 409 — create a new one instead.

curl -X POST "https://api.feeef.org/v1/image_generations/generate" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -F "storeId=YOUR_STORE_ID" \
  -F "prompt=Product hero shot on a marble table, warm light" \
  -F "aspectRatio=1:1" \
  -F "imageSize=2K"

# then poll:
curl -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/image_generations/{id}"

Image prompt templates

Reusable, admin-curated prompts (with attachments, propsSchema and props) that the image studio renders as one-tap presets. Reads are public and served from a server-side cache; writes are restricted to platform admins.

SDKs: ff.imagePromptTemplates.list(...) / .find(...) in both JavaScript and Dart.

One-shot AI actions

Synchronous RPC-style endpoints under /v1/actions. All require a Bearer token; store-scoped actions also check membership/permissions on the target store. Responses share the shape { "success": true | false, "message": "...", ... } with the payload alongside.

generateVoiceover takes text and/or attachments, optional voiceName (default Fenrir), model, enhanceScript, styleInstructions, and speakers (exactly two for multi-speaker dialogue). It returns audioUrl plus metadata with the enhanced script, token counts and the actual userCostDZD — voiceover is settled from real usage after generation, not the estimate.

curl -X POST "https://api.feeef.org/v1/actions/generateVoiceover" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "YOUR_STORE_ID",
    "text": "عرض خاص هذا الأسبوع — توصيل مجاني لكل الولايات!",
    "voiceName": "Fenrir",
    "enhanceScript": true
  }'

Template & landing-page AI

The endpoints behind the template editor's AI features — see Templates → AI for how the generated structures plug into TemplateData.

generateAiLandingPage runs a two-step flow (prompt enhancement, then one-shot generation of designSpec + defaults) in the background and creates the landing page plus a notification when done. It needs storeId, productId and a prompt and/or attachments; poll the job status roughly every 10 seconds until it reports completed with a landingPageId.

curl -X POST "https://api.feeef.org/v1/actions/generateAiLandingPage" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"storeId": "STORE_ID", "productId": "PRODUCT_ID", "prompt": "Classic luxury theme"}'

curl -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/actions/getAiLandingPageJobStatus?jobId=JOB_ID"

Chat (agent API)

User-scoped conversations with an agent that can call tools, use MCP servers, and follow user-defined rules and skills. All routes below sit under /v1/chat and require a Bearer token (one exception noted).

Conversations, messages & generations

Sending parts answers 202 with userMessageId, assistantMessageId, generationId and a transmitChannel (users/{userId}/chat/generations/{generationId}). Follow progress over realtime SSE on that channel, or poll the generation with sinceSeq.

Tool approval is a userEvent on the same messages endpoint. When the agent proposes a tool call that the conversation's toolPolicy doesn't auto-approve, reply with confirm_action and the action id. Other event types: user_input (answers to agent questions), choice_selected, cancel_action, task_toggled, block_action, regenerate, continue, edit_resend, and client_tool_result.

# create a conversation, send a message, approve a tool call
curl -X POST "https://api.feeef.org/v1/chat/conversations" \
  -H "Authorization: Bearer $FEEEF_TOKEN" -H "Content-Type: application/json" \
  -d '{"modelId": "gemini-flash-latest"}'

curl -X POST "https://api.feeef.org/v1/chat/conversations/{id}/messages" \
  -H "Authorization: Bearer $FEEEF_TOKEN" -H "Content-Type: application/json" \
  -d '{"parts": [{"type": "text", "text": "How many pending orders do I have?"}]}'

curl -X POST "https://api.feeef.org/v1/chat/conversations/{id}/messages" \
  -H "Authorization: Bearer $FEEEF_TOKEN" -H "Content-Type: application/json" \
  -d '{"userEvent": {"type": "confirm_action", "actionId": "ACTION_ID", "approved": true}}'

MCP servers, rules & skills

The agent can call tools on user-registered MCP servers (streamable HTTP, optional headers or OAuth). Rules inject user-authored markdown into the system prompt; skills are shareable SKILL.md packages with a marketplace.

The Dart SDK wraps all of this under ff.chat (conversations, messages, generations, jobs, mcpServers, models, billing, queue, rules, skills). The JavaScript SDK does not wrap the chat API yet — use axios against the paths above.

Billing & credits

• Provider costs (USD) are converted to credits with the platform exchange rate (default 260 DZD/USD) and a retail markup (default 2.5×). Reference attachments add a small per-file surcharge that scales with resolution.
• Image generations pre-check the wallet before dispatching. Insufficient balance answers 402 with code: "INSUFFICIENT_BALANCE" and details (requiredAmount, currentBalance, breakdown); the estimate is computed exactly like the final charge.
• Voiceover settles from actual token usage after generation and reports userCostDZD in the response metadata.
• Chat requires a positive balance to start a generation (402 otherwise). Mid-flight events — tool confirmations, answers to agent questions — always pass.
• Text generations whose prompt stays under the free-tier threshold (default 1,000 prompt tokens) are free.
• Use POST /v1/chat/estimate to show a price before running any capability. Charges appear as ai_generation transfers in the wallet history.