All MCP tools

This reference describes all 18 tools registered by Infinity Flow. REST paths below are relative to https://infinityflow.stream/api/v1. All arguments are strict JSON objects: unknown fields are rejected. IDs and requestKey values in examples are placeholders; use IDs returned by your account and generate a new UUID for each new creation intent.

Tool index, permissions and argument examples

Every listed scope is required in addition to an active base plan and automation entitlement. {} means no arguments. Output names refer to the exact shapes below.

Tool	Scope	REST	Example arguments	Output
get_account	account:read	GET /account	{}	Account
get_usage	usage:read	GET /usage	{}	Usage
list_models	account:read	GET /models	{}	Models
list_projects	projects:read	GET /projects	{}	Projects
create_project	projects:write	POST /projects	{"requestKey":"11111111-1111-4111-8111-111111111111","name":"Campaign"}	CreatedProject
update_project	projects:write	PATCH /projects/{id}	{"id":"22222222-2222-4222-8222-222222222222","name":"Campaign 2"}	OK
delete_project	projects:write	DELETE /projects/{id}	{"id":"22222222-2222-4222-8222-222222222222"}	OK
list_references	references:read	GET /references	{}	References
upload_reference	references:write	POST /references	{"requestKey":"33333333-3333-4333-8333-333333333333","projectId":"22222222-2222-4222-8222-222222222222","filename":"reference.png","data":"BASE64_IMAGE_BYTES"}	UploadedReference
delete_reference	references:write	DELETE /references/{id}	{"id":"33333333-3333-4333-8333-333333333333"}	OK
create_video	generations:write	POST /generations	{"requestKey":"44444444-4444-4444-8444-444444444444","prompt":"A forest at sunrise","aspect":"16:9"}	GenerationResult
create_image	generations:write	POST /generations	{"requestKey":"55555555-5555-4555-8555-555555555555","prompt":"A forest at sunrise","aspect":"9:16"}	GenerationResult
create_batch	generations:write	POST /batches	{"requestKey":"66666666-6666-4666-8666-666666666666","items":[{"prompt":"A forest at sunrise","aspect":"16:9","mediaKind":"video"}]}	BatchResult
get_batch	generations:read	GET /batches/{id}	{"id":"66666666-6666-4666-8666-666666666666"}	BatchResult
get_generation	generations:read	GET /generations/{id}	{"id":"77777777-7777-4777-8777-777777777777"}	GenerationResult
list_generations	generations:read	GET /generations	{"projectId":"22222222-2222-4222-8222-222222222222"}	Generations
cancel_generation	generations:write	POST /generations/{id}/cancel	{"id":"77777777-7777-4777-8777-777777777777"}	OK
get_download_url	media:read	GET /generations/{id}/outputs/0/download-ticket	{"id":"77777777-7777-4777-8777-777777777777"}	DownloadTicket

Input fields by tool

Tools	Required fields	Optional fields and behavior
get_account, get_usage, list_models, list_projects, list_references	None	None
create_project	requestKey: UUID; name: trimmed string, 1–100 characters	None; same key/name retrieves the original creation
update_project	id: project UUID; name: trimmed string, 1–100 characters	None
delete_project	id: project UUID	None; unfinished work or references used by pending work can block deletion
upload_reference	requestKey: UUID; projectId: UUID; filename: 1–150 characters; data: base64 image bytes	No remote URL or data-URL input; at most 11,200,000 base64 characters and 8 MiB decoded; actual image type is validated
delete_reference	id: reference UUID	None; references used by pending work are protected
create_video, create_image	requestKey: UUID, plus GenerationInput required fields	GenerationInput optional fields; do not pass mediaKind or model to these tools: the tool selects the kind
create_batch	requestKey: UUID; items: array of 1–100 GenerationInput objects	Plan maximum also applies: Creator 3, Pro 20, Enterprise 100; no per-item requestKey
get_batch	id: batch UUID	None
get_generation, cancel_generation, get_download_url	id: generation UUID	None; output index is always 0
list_generations	None	cursor: string up to 100 characters, pass returned nextCursor unchanged; projectId: UUID filter; fixed page size up to 24

GenerationInput

Field	Requirement	Type and accepted values
prompt	Required	Trimmed nonempty string, up to 4,000 characters
aspect	Required	16:9 or 9:16
title	Optional	String up to 100 characters
projectId	Optional	UUID of your private project
referenceIds	Optional	Array of up to 3 distinct reference UUIDs
referenceId	Optional	Single reference UUID, supported compatibility field
durationSeconds	Optional	Only 10; does not enable arbitrary duration
outputCount	Optional	Only 1; a batch is the way to create several jobs
mediaKind	Batch items only	video or image; omitted means video
model	Batch items only	studio-video or studio-image; must match kind

Use one reference field convention consistently. Inputs still pass ownership and generation validation; schema acceptance does not bypass those checks. Single-image tools accept the shared duration/output fields, but duration is not an image animation setting. Read list_models for current capabilities; no resolution field is exposed.

Success and failure envelopes

A successful tool returns the REST JSON unchanged inside structuredContent.result, plus the same JSON serialized into content[0].text:

{
  "structuredContent": {
    "result": {
      "generation": {
        "id": "77777777-7777-4777-8777-777777777777",
        "state": "queued"
      }
    }
  },
  "content": [
    {
      "type": "text",
      "text": "{\"generation\":{\"id\":\"77777777-7777-4777-8777-777777777777\",\"state\":\"queued\"}}"
    }
  ]
}

The generation in this envelope illustration is abbreviated; the complete shape follows. Creation is accepted asynchronously (REST status 202), not completed synchronously. Tool payloads do not expose the REST status or Location header.

Tool execution failures return isError: true and a text content block containing the error JSON. Exceptions use {error:{code,message,requestId,details?,usage?}}. Delegated domain errors can instead return the existing {error: string} form; clients must check isError and parse the returned body rather than assume every error has identical fields. Protocol/schema errors and HTTP authentication failures occur outside the tool execution envelope.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"code\":\"INSUFFICIENT_SCOPE\",\"message\":\"This credential does not permit this operation.\",\"requestId\":\"88888888-8888-4888-8888-888888888888\"}}"
    }
  ]
}

Complete output shapes

These shapes describe structuredContent.result. ? means optional, null is an actual JSON value; timestamps labelled ISO are ISO 8601 UTC strings. Project/reference timestamps are epoch milliseconds, not ISO strings.

Account = {
  account: { id: UUID, name: string },
  entitlements: {
    planId: "legacy"|"creator"|"pro"|"enterprise"|null,
    active: boolean, automationEnabled: boolean,
    dailyVideoLimit: integer|null, maxBatchSize: integer,
    maxOutstandingJobs: integer, maxActiveGenerations: 1, priority: integer,
    legacyPriceLocked: boolean, basePriceMinor: integer|null,
    currency: string|null, market: string|null, intervalMonths: integer|null,
    validFrom: epochMilliseconds, validUntil: epochMilliseconds|null,
    policyVersion: string
  }
}
Usage = {
  date: "YYYY-MM-DD", timeZone: "America/Sao_Paulo", resetsAt: ISO,
  limit: integer|null, reserved: integer, consumed: integer,
  remaining: integer|null
}
Models = { models: [
  { id: "studio-video", kind: "video", durationSeconds: 10,
    aspects: ["16:9","9:16"], maxReferences: 3 },
  { id: "studio-image", kind: "image",
    aspects: ["16:9","9:16"], maxReferences: 3 }
] }
Projects = { projects: [{id: UUID, name: string, createdAt: epochMilliseconds,
                        updatedAt: epochMilliseconds}] }
CreatedProject = { project: {id: UUID, name: string, created: epochMilliseconds,
                             updated: epochMilliseconds} }
References = { references: [{id: UUID, projectId: UUID, filename: string,
  mime: string, size: integer, createdAt: epochMilliseconds}] }
UploadedReference = { reference: {id: UUID, filename: string} }
GenerationResult = { generation: Generation }
BatchResult = { batch: {id: UUID, generations: Generation[]} }
Generations = { generations: Generation[], nextCursor: string|null }
OK = { ok: true }
DownloadTicket = { url: string }
Generation = {
  id: UUID, projectId: UUID, batchId?: UUID|null, batchIndex?: integer|null,
  title: string, mediaKind: "video"|"image",
  model: "studio-video"|"studio-image", aspect: "16:9"|"9:16",
  state: "queued"|"processing"|"succeeded"|"failed"|"cancelled"|"attention_required",
  createdAt: ISO, updatedAt: ISO, readyAt: ISO|null, expiresAt: ISO|null,
  outputs: [{ index: 0, mime: string, kind: "video"|"image", size: integer,
    downloadAvailable: boolean, expiresAt: ISO,
    downloadUrl: string|null, playUrl: string|null, thumbnailUrl: string|null }]
}

outputs is empty before an available result. Media URLs inside Generation point to authenticated REST endpoints; the URL from get_download_url is a temporary signed URL with up to 90 seconds validity, shortened near media expiry. Never forward an Infinity Flow Authorization header to its storage host. Media remains available for 24 hours from ready time; request a fresh ticket if needed within that window.

list_projects returns at most 100 records; list_references returns at most 100 records. They do not return pagination cursors. list_generations returns at most 24 and a nullable nextCursor. get_batch preserves item presentation order; execution is not promised to be parallel or in that order.

Operational rules and errors

Persist requestKey and payload before calling create_project, upload_reference, create_video, create_image or create_batch. MCP maps requestKey to the REST Idempotency-Key header. Reuse both after timeout; changing payload under the same key yields IDEMPOTENCY_CONFLICT. JSON-RPC request IDs are not durable generation keys. Renaming/deleting/cancelling do not take requestKey.

Batch admission is all or nothing; later outcomes are per generation. Cancellation returns {ok:true} when allowed, not a fresh Generation object. An active execution lease or started submission can produce a conflict; cancellation does not blindly cancel uncertain paid work.

Common errors include INVALID_CREDENTIAL (expired/revoked auth), AUTOMATION_REQUIRED (plan/add-on), INSUFFICIENT_SCOPE, REQUEST_RATE_LIMIT, DAILY_VIDEO_LIMIT, BATCH_LIMIT, INVALID_PARAMETER, INVALID_CURSOR, INVALID_REFERENCE, REFERENCE_TOO_LARGE, IDEMPOTENCY_CONFLICT, and NOT_FOUND. Some domain conflicts use REQUEST_REJECTED. Inspect usage/reset metadata for a quota failure; do not submit a different key to evade it. HTTP auth/rate failures should be handled before attempting to parse a tool result.

For transport and authorization see connection and OAuth. REST details and errors are in the API reference.