AI

Every AI endpoint lives under /v1/ai/*. Feeef never calls an AI provider directly: each request runs on Feeef Cloud, which owns models, prompts for Cloud products, provider routing and the exact usage receipt. Feeef adds your store and product data, keeps history, and charges your wallet from the receipt.

Conventions

Auth and scopes

All routes need a Bearer token except the public reads (image-generations/gallery, image-prompt-templates). Tokens need ai.read for GET and ai.generate for everything else; first-party tokens (*) always pass. Otherwise the API answers:

// 403, WWW-Authenticate: Bearer error="insufficient_scope", scope="ai.generate"
{ "error": { "code": "insufficient_scope", "message": "Explicit ai.generate access is required" } }

Store-scoped calls also check your member permissions on storeId.

Idempotency

Every paid request needs an Idempotency-Key header (1–200 printable ASCII characters; voice calls use a UUID). Persist the key before sending and reuse it on retry:

A replay returns exactly what the first call returned, including success: false bodies: use a new key to try again after a failure. The SDKs manage keys for you (CloudAiWorkflowIntents in Dart, ff.withAiWorkflow(key, …) in JavaScript).

Async results

Long jobs return immediately and finish in the background:

• Image records (images, image-generations, image-landing-pages, studio assets) create an ImageGeneration with status pending → processing → completed (or failed, reason in error). Follow it on the realtime channels image_generations/{id}, users/{userId}/image_generations or stores/{storeId}/image_generations (created, updated, deleted events), or poll GET /v1/ai/image-generations/{id}.
• HTML landing pages return a jobId; poll GET /v1/ai/landing-pages/jobs/{jobId}.
• Raw requests return a job; poll GET /v1/ai/requests/{id}.

Billing

AI is postpaid. When Cloud returns the final receipt (charged_micros, in USD micros), Feeef converts it once — micros / 1,000,000 × exchange rate × retail markup, rounded up to 0.001 DZD — and records one ai_generation transfer from your wallet. There is no hold and no balance pre-check; a wallet can go negative and must be topped up. Failed steps that already ran are billed. Admission limits per user: 4 active jobs and 20 new jobs per minute, otherwise 429 feeef_ai_admission_limit (nothing started, nothing charged).

Responses and errors

• Text, code and sync image/voice endpoints answer 200 with { "success": true | false, "message", ... }. AI or permission failures are success: false with error.
• Cloud errors keep their status: { "error": { "code", "message", "requestId" } }.
• Uploads are limited to 20 MiB per request (413 ai_body_too_large).

Catalog

Pass storeId to use the store's Cloud workspace; without it your personal workspace is used. A collection rung is { rank, label, description, model } — show it as a quality slider.

Raw Cloud access

Direct access to any Cloud operation (chat/completions, responses, embeddings, images/*, audio/*, videos, google/*, anthropic/messages) with Feeef billing.

body.model must come from /v1/ai/models. A job is { id, status, endpoint, cloudRequestId, imageGenerationId, billing: { currency: "DZD", chargedMicros, chargeDzd, settled }, error, result }.

Text

Natural language → a validated draft. Nothing is saved; your app applies the draft. All take storeId, input, optional attachments (image, url, audio, product, store) and modelId.

curl -X POST "https://api.feeef.org/v1/ai/text/product-draft" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"storeId":"STORE_ID","input":"Black leather wallet, 2500 DZD, 3 colors"}'

Code

Storefront code and builder structures. See Templates → AI for how results plug into TemplateData.

Template code needs store_templates.write, template_components.write, product_landing_pages.write or pages.write on the store.

HTML landing pages

The job writes the page copy and design, then creates the ProductLandingPage and sends a push notification. Poll every ~10 seconds.

Images

POST /v1/ai/images (JSON or multipart) takes model (a Cloud image model), prompt, options (from the model's feeef_image choices: aspect ratio, size, quality, background, format), attachments (image URLs on Feeef storage, store, product), optional imageFile and maskFile (PNG with alpha), id to append to an existing record, and storeId.

POST /v1/ai/image-generations takes prompt, storeId, model, aspectRatio, imageSize (1K/2K/4K), resolution, attachments (image, store, product, audio), imageFile, background, quality, outputFormat, googleSearch, imageSearch.

final gen = await ff.ai.generateImage(/* model, prompt, options … */);
// then listen on users/{userId}/image_generations, or:
final record = await ff.imageGenerations.find(gen['id']);

Image landing pages

One tall product poster image (default 9:32), built by Cloud in two steps: a text model writes the copy deck from your product data and photos, then an image model renders it. The result is an ImageGeneration tagged image_landing_page.

Start — text (the brief), attachments (image, product, store), storeId (its Cloud workspace owns templates and the job), templateId, answers (keyed by question key), imageModel (a ladder rung), aspectRatio, imageSize, background, sectionsCount (2–12), loadProductImage (default true; send false when you pass the photos yourself).

Templates are visual direction plus optional questions:

{
  "name": "Gold Ramadan",
  "description": "Matte gold, white marble, soft light",
  "prompt": "Palette: matte gold on white marble. Headline: {{headline}}.",
  "preview_image_url": "https://storage.feeef.net/…/preview.jpg",
  "fields": [
    { "key": "headline", "type": "text", "label": "Headline" },
    { "key": "mood", "type": "select", "label": "Mood", "options": ["Calm", "Festive", "Luxury"] }
  ]
}

Field types: text, textarea, select, multiselect, toggle, color, number. All answers are optional; {{key}} in the prompt takes the answer and other answers are passed as labelled notes. Platform templates are read-only.

Questions — { storeId?, text?, attachments?, templateId?, locale: ar|fr|en } with an Idempotency-Key → { summary, templateFields, fields, billing: { chargeDzd } }.

final ladder = await ff.ai.collection('image-landing-page', storeId: storeId);
final templates = await ff.ai.imageLandingPages.templates(storeId: storeId);
final res = await ff.actions.generateImageLandingPage(
  text: 'Ramadan offer, free delivery',
  attachments: [ProductAttachment(value: productId, label: 'Wallet')],
  storeId: storeId,
  templateId: templates.first.id,
  imageModel: ladder?.rungs.last.model.id,
);

Voice

Voice calls are synchronous (up to ~170 s). If a call ends while the job is still running you get 503 with the job id — call again with the same Idempotency-Key (a UUID) or use /speech/retry. Passing projectId to /speech records the take in that project.

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

Studios

Brand, social-post and UI mockup studios. Asset calls return immediately with an ImageGeneration id (follow it like any image record).

SDK map

The generated API reference lists every field of every route.