Skip to main content

​
Full API Reference (For Advanced Users)

This section provides a detailed reference for interacting directly with the APUS AI Router Process. This is for advanced users who choose not to use the @apus/ai library. All interactions are standard AO messages.

​
Purchasing Credits with $APUS

Environment: This operation is performed on the AO Legacy Network. aos your_process
To purchase Credits, you perform a standard Transfer to the $APUS token process, with the Recipient tag pointing to our Router Process.
  • Target: mqBYxpDsolZmJyBdTK8TJp_ftOuIUXVYcSQ8MYZdJg0 (APUS Token Process ID)
  • Action: Transfer
TagTypeRequiredDescription
ActionstringYesMust be "Transfer".
RecipientstringYesThe AI-Infer Router Process ID: TED2PpCVx0KbkQtzEYBo0TRAO-HPJlpCMmUzch9ZL2g
`.
QuantitystringYesThe amount of $APUS tokens to transfer. The credits you receive will be based on the current exchange rate.
X-ReasonstringYesMust be Buy-Credits to indicate the purpose of the transfer.
Example Lua Request: 
ao.send({
    Target = "mqBYxpDsolZmJyBdTK8TJp_ftOuIUXVYcSQ8MYZdJg0", -- $APUS Token Process
    Recipient = "TED2PpCVx0KbkQtzEYBo0TRAO-HPJlpCMmUzch9ZL2g
", -- Our Router Process
    Action = "Transfer",
    Quantity = "1000000000000", -- e.g., 1 $APUS (10^12 Armstrongs)
    ["X-Reason"] = "Buy-Credits"
})

​
AI Inference Request

To initiate an AI inference, send a message directly to our Router Process.
  • Target: TED2PpCVx0KbkQtzEYBo0TRAO-HPJlpCMmUzch9ZL2g ` (AI-Infer Router Process ID)
  • Action: Infer
Request Message Tags:
TagTypeRequiredDescription
ActionstringYesMust be "Infer".
DatastringYesThe text prompt to send to the AI model.
X-PromptstringNo[Deprecated] The text prompt to send to the AI model.
X-ReferencestringNo, but recommended!A unique identifier for your request. If omitted, the message’s own ID will be used. It’s highly recommended for tracking responses.
X-SessionstringNoAn existing session ID to continue a conversation. If omitted, a new session is created.
X-OptionsjsonNoA JSON string containing runtime parameters to customize the inference. See the table below for available options.
X-Options JSON Parameters: These parameters allow you to control the behavior of the Gemma3-27B model for each request.
ParameterTypeDefaultRangeDescription
temperaturefloat0.70.0 - 2.0Controls randomness. Lower values are more deterministic, higher values are more creative.
top_pfloat0.90.0 - 1.0Nucleus sampling. The model considers only the tokens with the highest probability mass.
max_tokensinteger20481 - 8192The maximum number of tokens to generate in the response.
Example Lua Request: 
ao.send({
    Target = "TED2PpCVx0KbkQtzEYBo0TRAO-HPJlpCMmUzch9ZL2g
",
    Action = "Infer",
    Data = "Who are you?",
    ["X-Options"] = '{"temperature": 0.8, "max_tokens": 150}'
})

​
AI Inference Response

To get the response of your AI inference, handle message send by our Router Process. Example Lua Handler: 
Handlers.add(
    "AcceptResponse",
    { Action = "Infer-Response" },
    function (msg)
	    // check msg.Code for error
	    if msg.Code then
		    print(msg.Code)
		    print(msg.Data)
		  end
	    print(msg.Data)
	    print(msg["X-Reference"])
	    print(msg["X-Session"])
	  end
)
On Success
TagTypeDescription
Actionstring"Infer-Response"
DatajsonResponse of AI Inference in json format.
Data.attestationstringGPU attestation report.
Data.resultstringAI Inference result.
X-SessionstringThe session id you passed in.
X-ReferencestringThe reference id you passed in, you not provided, generated automatically.
On Error
TagTypeDescription
Actionstring"Infer-Response"
CodestringError code.
X-ReferencestringError message.

​
Patch API (Read-Only State via patch@1.0)

Brief Intro: Patch API is introduced by HyperBEAM for improves performance for web frontends and data services by replacing the need for dryrun calls, which were a known bottleneck on legacynet. Prerequisites: Please read https://cookbook_ao.arweave.net/guides/migrating-to-hyperbeam/exposing-process-state.html to learn how to migrate to HyperBEAM.
Our Router Process uses HyperBEAM’s patch@1.0 device to expose its internal state for efficient, read-only access over HTTP. This is the best way to monitor your tasks and credits without sending messages.
  • Base URL: http://72.46.85.207:8734/{Router_Process_ID}~process@1.0/now/cache/
  • Router Process ID: TED2PpCVx0KbkQtzEYBo0TRAO-HPJlpCMmUzch9ZL2g `
Available Cache Endpoints: You can append the following paths to the base URL to query specific data.
  • /credits/: Get the current credit balance for a specific process.
    • Example: .../now/cache/credits/UIpgvCAjEajkAwH7qAAun0ybS3awepNO_kXa70cTZoU
  • /tasks/: Get the status and details of a specific inference task. The task_reference is {client_process_id}-{user_reference}.
    • Example: .../now/cache/tasks/UIpgvCAjEajkAwH7qAAun0ybS3awepNO_kXa70cTZoU-1721644800
    • Response Structure (task object): 
      {
  "status": "successed", // "pending", "processing", "successed", or "failed"
  "created_at": 1721644800,
  "processed_at": 1721644815,
  "prompt": "What is Arweave?",
  "options": "{\\"temperature\\":0.7}",
  "session_id": "session-12345",
  "result": "Arweave is a decentralized storage network...",
  "client": "UIpgvCAjEajkAwH7qAAun0ybS3awepNO_kXa70cTZoU",
  "worker": "WORKER_PROCESS_ID"
}
  • /taskStats: Get real-time statistics for the entire service.
    • Example: .../now/cache/taskStats
    • Response Structure: { "total_tasks": 150, "pending": 10, "processing": 5, "successed": 130, "failed": 5 }