AI projects

Manage AI projects (workspace context for feeds, jobs, chat, and library). Use your registration domain in every form body — not the API hostname.

Two upstream surfaces exist on https://api.gommo.net:

API	When to use
Legacy `POST /ai/projects`	Minimal project list; pick `id_base` for `project_id` on jobs and newfeeds
V2 `POST /api/v2/ai-projects`	Full dealer-style manager: scopes, members, session counts, create/update/delete

Playground

Playground — Home feed when running npm run docs:stack: Project workspace, Project library, Project billing, and Platform (legacy list under Legacy API). Worker map below.

Authentication

Authorization: Bearer <access_token>
Form field access_token (same token)
domain = registration domain ($env:GOMMO_API_DOMAIN in examples below)

V2 calls also send device_id, device_name, and device_info (JSON string). The optional gateway fills device fields when the client omits them.

Legacy list

powershell

$domain = $env:GOMMO_API_DOMAIN
if (-not $domain) { throw 'Set GOMMO_API_DOMAIN' }
$h = @{ Authorization = "Bearer $env:TOKEN"; 'Content-Type' = 'application/x-www-form-urlencoded' }
Invoke-RestMethod -Method Post -Uri 'https://api.gommo.net/ai/projects' -Headers $h -Body "access_token=$env:TOKEN&domain=$domain"

Response: { "success": true, "data": [ { "id", "id_base", "name", … } ] } (pass-through).

Self-host: POST {gateway}/gateway/projects (JSON body optional device fields).

V2 project manager

Single endpoint: POST https://api.gommo.net/api/v2/ai-projects
Content-Type: application/x-www-form-urlencoded

Dispatch with form field action:

`action`	Required fields	Notes
`list`	`domain`, `access_token`	Optional `language`. Returns `data[]` with `my_scopes`, `session_count`, `member_preview`, …
`create`	`name`, `description`	Description ≥ 10 characters (upstream). Returns updated list or project payload (pass-through).
`get`	`id_base`	One project in `data` (object). Optional `password` when project is `protected` — unlock (dealer Mở dự án). Wrong password: `success: false`, `needs_password: true`, message (HTTP often still 200).
`set_password`	`id_base`, `password`	Tab Chi tiết — MẬT KHẨU TÀI DỰ ÁN / Cập nhật mật khẩu. Sets `protected: true`. Empty `password` clears (dealer: Để trống = xóa mật khẩu). Response `projectInfo` + `data`.
`update`	`id_base`, `name`, `description`	Same description rule as create. Response may include `projectInfo` and `data` (duplicate project object). Name/description only — not project password.
`delete`	`id_base`	Use `id_base`, not numeric `id`. Response often `{ "data": { "id_base", "is_deleted": 1 } }`.
`member_list`	`id_base`	Tab Members — see Member list response below.
`member_kick`	`id_base`, `user_id`	Remove a member — `user_id` is numeric from `member_list` (not `@username`). Verified on dealer UI.
`invite`	`id_base`, `identifier`, `role`, `access`, `scopes`	Tab Mời — `identifier` is username (not display name). `role`: `member` \| `mod` \| `admin`. `scopes`: JSON string (copy from Network per role). Optional `description`.
`invite_revoke`	`invite_id`	Thu hồi pending invite — `invite_id` from `member_list` → `data.invites[]`.
`set_budget`	`id_base`, `budget`	Tab Limits — integer credits; `0` = unlimited upstream. Response includes `projectInfo` + `data` with `budget`, `credit_balance`, `share_credit_enabled`.
`stats`	`id_base`, `period`	Tab Statistics (`Thống kê`) — see Project statistics.
`activity_list`	`id_base`, `limit`, `offset`	Tab Activity history (`Lịch sử hoạt động`) — see Activity history.

Optional on all actions: language (e.g. vi or VI), device fields.

Project credit pools (tab Budget) use a separate endpoint — see Credit pools.

PowerShell examples (V2)

powershell

$domain = $env:GOMMO_API_DOMAIN
if (-not $domain) { throw 'Set GOMMO_API_DOMAIN' }
$h = @{ Authorization = "Bearer $env:TOKEN"; 'Content-Type' = 'application/x-www-form-urlencoded' }
$uri = 'https://api.gommo.net/api/v2/ai-projects'

$list = "access_token=$env:TOKEN&domain=$domain&action=list&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $list

$create = "access_token=$env:TOKEN&domain=$domain&action=create&name=My+project&description=At+least+ten+chars+here&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $create

$idBase = '<id_base_from_list>'
$get = "access_token=$env:TOKEN&domain=$domain&action=get&id_base=$idBase&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $get

$upd = "access_token=$env:TOKEN&domain=$domain&action=update&id_base=$idBase&name=My+project&description=Updated+description+here&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $upd

$del = "access_token=$env:TOKEN&domain=$domain&action=delete&id_base=$idBase&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $del

$members = "access_token=$env:TOKEN&domain=$domain&action=member_list&id_base=$idBase&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $members

$userId = 75965
$kick = "access_token=$env:TOKEN&domain=$domain&action=member_kick&id_base=$idBase&user_id=$userId&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $kick

$budget = "access_token=$env:TOKEN&domain=$domain&action=set_budget&id_base=$idBase&budget=48790&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $budget

$setPwd = "access_token=$env:TOKEN&domain=$domain&action=set_password&id_base=$idBase&password=YOUR_PASSWORD&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $setPwd

$getProtected = "access_token=$env:TOKEN&domain=$domain&action=get&id_base=$idBase&password=YOUR_PASSWORD&language=vi"
Invoke-RestMethod -Method Post -Uri $uri -Headers $h -Body $getProtected

Self-host gateway (Mode B)

POST {gateway}/gateway/ai-projects with JSON (Bearer required). Gateway adds domain from tenant/env when omitted. Aliases: idBase, projectId → id_base; userId → user_id; inviteId → invite_id.

OpenAPI: openapi.yaml — path /gateway/ai-projects.

json

{ "action": "list", "language": "vi" }

json

{
  "action": "get",
  "id_base": "<id_base_from_list>",
  "password": "<when protected — dealer Mở dự án>",
  "language": "vi"
}

json

{
  "action": "set_password",
  "id_base": "<id_base_from_list>",
  "password": "<new password — empty string clears>",
  "language": "vi"
}

json

{
  "action": "update",
  "id_base": "<id_base_from_list>",
  "name": "My project",
  "description": "At least ten characters",
  "language": "vi"
}

Playground (Home feed)

When running npm run docs:stack, Playground proxies gateway routes (same-origin). The Home feed worker menu uses dealer-oriented section names — Legacy API, Project workspace, Project library, Project billing, Platform — with one worker per flow (labels match the Playground UI; JSON action is in the table):

Section	Playground worker	JSON `action`	Main form fields
Legacy API	List projects (legacy)	— (`POST /gateway/projects`)	`language`
Project workspace	Browse projects	`list`	`language`
Project workspace	Open project	`get`	`id_base`, optional `password`, `language`
Project workspace	Project password	`set_password`	`id_base`, `password` (empty clears), `language`
Project workspace	Create project	`create`	`name`, `description`, `language`
Project workspace	Edit project	`update`	`id_base`, `name`, `description`, `language`
Project workspace	Members & invites	`member_list`	`id_base`, `language`
Project workspace	Invite member	`invite`	`id_base`, `identifier`, `role`, optional access, `language`
Project workspace	Revoke invite	`invite_revoke`	`invite_id`, `language`
Project workspace	Remove member	`member_kick`	`id_base`, `user_id`, `language`
Project workspace	Spending limit	`set_budget`	`id_base`, `budget`, `language`
Project workspace	Usage statistics	`stats`	`id_base`, `period`, `language`
Project workspace	Audit log	`activity_list`	`id_base`, `limit`, `offset`, `language`
Project workspace	Delete project	`delete`	`id_base`, `language`
Project workspace	Advanced: custom action	any captured `action`	`action` + optional fields (pass-through)
Project library	Images / Videos	`list` (files-manager)	`project` (`id_base`), `media_type`, `limit`, `offset`, `signed_previews`
Project library	Audio / Music	gateway project-media routes	`project_id`, `language`
Project billing	List pools … Shared credits	credit-pools actions	See Credit pools
Platform	News & updates / Notifications / Signed-in devices	`getAll` (news) · — (inbox/devices)	News & updates; inbox uses `/gateway/notifications`

Home feed workers do not use library Limit / After ID fields — those apply to media library lists only.

Request tab vs Send: the Request preview may show placeholders (e.g. {id_base}, <if protected> for password) when inputs are empty. Send sends only filled values (optional password on get is omitted until you type it). set_password always includes the password key (empty string clears upstream).

Project statistics

Dealer project modal tab Statistics (Thống kê) calls the same V2 endpoint with action=stats.

Field	Required	Notes
`id_base`	yes	Project UUID
`period`	yes	Must match dealer sub-tabs (verified)

Dealer UI	`period`
All	`all`
Hôm nay	`today`
Hôm qua	`yesterday`
Tháng này	`this_month`
Tháng trước	`last_month`

Response (pass-through): data.project (snapshot), data.summary (credit spend/refund/deposit, conversations, media order counts), data.chart (granularity, labels[], series such as spend, refund, conversations, apps), plus period, period_from, period_to, credit_balance, budget.

Not usage-history

This is per-project modal stats on ai-projects. Account-wide usage charts use POST /api/v2/usage-history (action=stats) — see Usage history (gateway preview).

Mode B:

json

{
  "action": "stats",
  "id_base": "<project id_base>",
  "period": "all",
  "language": "vi"
}

Playground: Usage statistics.

Activity history

Dealer project modal tab Activity history (Lịch sử hoạt động) uses action=activity_list on the same V2 endpoint.

Field	Required	Notes
`id_base`	yes	Project UUID
`limit`	no	Dealer UI sends 50 on first load
`offset`	no	0 for first page; increase by `limit` for pagination

Response (pass-through): data.items[] — audit rows with actor fields, localized summary, event action codes (not the same strings as API actions like invite or member_kick), target_type, target_id, payload (object or empty array), created_time (Unix seconds).

Sample action values seen in captures: project.create, project.update, budget.set, share_credit.on, share_credit.off, member.invite, member.revoke, member.kick, member.accept. Pool create / deposit / delete may appear when upstream logs them — not guaranteed in every project history.

Mode B:

json

{
  "action": "activity_list",
  "id_base": "<project id_base>",
  "limit": 50,
  "offset": 0,
  "language": "vi"
}

Playground: Audit log.

Member list response

action=member_list returns (pass-through shape):

data.members[] — each member: user_id, username, name, email, avatar, role, access, is_owner, status, nested scopes (chat, media, manage, …).
data.invites[] — pending invites (empty when none).
data.my_role, data.my_scopes — current session; UI uses my_scopes.manage.kick (and per-member scopes) to show kick / budget actions.

Kick member (verified)

Mode B:

json

{
  "action": "member_kick",
  "id_base": "<project id_base>",
  "user_id": 75965,
  "language": "vi"
}

Gateway aliases: idBase / projectId → id_base; userId → user_id.

Invite member (verified)

Mode B:

json

{
  "action": "invite",
  "id_base": "<project id_base>",
  "identifier": "hao26099",
  "role": "member",
  "access": "view",
  "scopes": { "...": "copy full object from dealer Network for this role" },
  "description": "Optional note",
  "language": "vi"
}

Gateway defaults access when omitted: member → view, mod / admin → edit. Aliases: email / username → identifier.

Business failure (HTTP 200): { "error": 1, "message": "Không tìm thấy tài khoản", … } when identifier does not resolve a user.

Revoke invite (verified)

json

{
  "action": "invite_revoke",
  "invite_id": "<uuid from data.invites[]>",
  "language": "vi"
}

Alias: inviteId → invite_id.

Using `project_id` elsewhere

From list or get, use id_base as project_id on:

POST …/ai/newfeeds
Job create forms on v2.api.gommo.net
Library album/list calls

Built-in default project: id_base = "default".

Credit vs budget

Field / UI	Meaning
Account balance (profile menu)	User wallet — not automatically spent on a project
`budget` on project (`set_budget`)	Cap how much the project may use (`0` = unlimited)
`credit_balance` on project	Spendable balance on the project (often 0 until pools are funded)
Credit pools	Tab Budget — `list`, `create`, `deposit` (Bơm), `delete`, ledger, share credit

Jobs and media creation charge project pools when share credit is enabled, not the raw wallet total.

Dealer tab Media (Ảnh / Video / Audio / Music) uses separate endpoints from ai-projects. Scope is the project UUID (id_base from list).

Images & video (`files-manager`)

POST https://api.gommo.net/api/v2/files-manager — action=list

Field	Required	Notes
`project`	yes	Project UUID (not `project_id`)
`media_type`	yes	`image` or `video`
`status`	no	Dealer sends `ready`
`signed_previews`	no	`true` — preview URLs in `data.items[]`
`limit`	no	UI 30
`offset`	no	Pagination

Response: data.items[] (id_hash, media_type, preview.url, original_name, status, …), limit, offset.

Mode B: POST {gateway}/gateway/files-manager JSON. Playground: Images / Videos (Project library).

Dealer may also call POST /ai/images or POST /ai/videos with project_id — captures often return empty data; prefer files-manager for the grid UI.

Search box (Tìm kiếm…): dealer UI filters client-side — files-manager action=list payload unchanged (no search / q field). Filter data.items[] locally (e.g. original_name).

Audio

POST https://api.gommo.net/ai/audio — project modal tab Audio:

Field	Required	Notes
`project_id`	yes	Project UUID
`action_type`	yes	`get.list` (verified modal; not TTS `getLists`)

Mode B: POST {gateway}/gateway/project-media/audio. Playground: Audio.

Music

POST https://api.gommo.net/api/apps/go-mmo/ai_musics/getAll (form):

Field	Required
`project_id`	yes
`domain`, `access_token`, device	yes

Mode B: POST {gateway}/gateway/project-media/music. Playground: Music.

Distinct from user library musics (/ai/library/musics) and from job create APIs.

Unknown `action` values (pass-through)

The gateway typed handlers cover the action table above (list through activity_list, including set_password). For a new upstream action not yet in OpenAPI, POST {gateway}/gateway/ai-projects can forward extra JSON keys via invokeAiProjectsV2 when you send a captured payload. Prefer adding a typed handler after Network verify.

Playground: Advanced: custom action — set action and fill optional fields; for standard flows use the dedicated workers (invite, kick, project password, …).

Project credit pools and share credit use Credit pools (create, deposit, delete, ledger, set_share_credit; deposit needs wallet ≥ amount + 100_000 reserve; delete may not refund the personal wallet).

Not covered here

Media upload actions on the tab (beyond list) — capture separately.

AI projects ​

Authentication ​

Legacy list ​

V2 project manager ​

PowerShell examples (V2) ​

Self-host gateway (Mode B) ​

Playground (Home feed) ​

Project statistics ​

Activity history ​

Member list response ​

Kick member (verified) ​

Invite member (verified) ​

Revoke invite (verified) ​

Using project_id elsewhere ​

Credit vs budget ​

Project modal — Media tab ​

Images & video (files-manager) ​

Audio ​

Music ​

Unknown action values (pass-through) ​

Not covered here ​

AI projects

Authentication

Legacy list

V2 project manager

PowerShell examples (V2)

Self-host gateway (Mode B)

Playground (Home feed)

Project statistics

Activity history

Member list response

Kick member (verified)

Invite member (verified)

Revoke invite (verified)

Using `project_id` elsewhere

Credit vs budget

Project modal — Media tab

Images & video (`files-manager`)

Audio

Music

Unknown `action` values (pass-through)

Not covered here