invoke_ai_model¶

ArtificialIntelligenceApi.invoke_ai_model(model_id, role_id, ai_model_invocation, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Invoke model

Starts an asynchronous text generation against an enabled AI model. A 200 means accepted, not complete: the call records an invocation with status IN_PROGRESS, and returns immediately with an InvocationId. Poll GET /ai/models/{model_id}?action=invoke&invocation_id=<id> until InvocationStatus is no longer IN_PROGRESS. It becomes COMPLETED with a ModelResponse, or FAILED with a FailureReason. Preconditions: the model must exist and be Enabled; a disabled model returns AI-1007 as a 400. The prompt is capped at 128000 characters. Input and output modality are fixed to TEXT for this endpoint. Guard rails are always applied: Provide GuardrailId to pin a specific Amorphic guard rail , otherwise the environment’s default guard rail is used. When a guard rail intervenes, it is recorded on the invocation record rather than returned here. Not idempotent — every call creates a new invocation. Invocation records are retained for 30 days and then expire.

Parameters:

model_id (str) – Bedrock model identifier as stored by Amorphic, for example anthropic.claude-sonnet-4-6. The model must be Enabled; an unknown model_id returns IPV-1002 as a 500, not a 404. (required)
role_id (str) – User role id (required)
ai_model_invocation (AIModelInvocation) – (required)
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

AIModelInvocationResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /ai/models/{model_id}

Request¶

Prompt only, default guard rail

{
  "UserInput": "Summarize the quarterly revenue trend in two sentences."
}

Pinned guard rail and per-invocation parameters

{
  "UserInput": "Summarize the quarterly revenue trend in two sentences.",
  "GuardrailId": "7f3c1a9e-2b4d-4f68-9c05-8ad1e6b2c740",
  "ModelParameters": {
    "temperature": 0.2,
    "max_tokens": 512
  }
}

Success (HTTP 200)¶

Invocation accepted and queued. Generation has not run yet — retain InvocationId and poll `GET /ai/models/{model_id}?action=invoke&invocation_id=<id>` for the result.

Request / response example

{
  "Message": "Model invocation triggered successfully",
  "InvocationId": "7c2f9b18-4d3a-4e51-9b6c-0a5e8d2f1436"
}

Errors¶

Documented error codes: AI-1007, IPV-1012, IPV-1002, AUTH-1014, DB-1001, GE-1013, GE-1008.

HTTP 400

Input validation failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AI-1007 (model exists but is not enabled), IPV-1012 (UserInput longer than 128000 characters), IPV-1002 (GuardrailId does not match an Amorphic guard rail). AUTH-1014 from the role check is also returned here, not as a 403.

modelNotEnabled

{
  "Message": "AI-1007 - Model is not enabled"
}

promptTooLarge

{
  "Message": "IPV-1012 - Prompt too large. Prompt length must be lower than 128000"
}

invalidGuardrail

{
  "Message": "IPV-1002 - guardrail with the specified identifier was not found. Please use a valid amorphic guardrail."
}

HTTP 500

Backend failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1002 (unknown model_id), DB-1001 (invocation record could not be persisted), GE-1013 (background invocation could not be started), GE-1008 (catch-all). The invocation record is written before the background invocation is triggered, so a DB-1001 leaves nothing running and a GE-1013 leaves an IN_PROGRESS record that expires via TTL.

recordPersistFailed

{
  "Message": "DB-1001 - Failed to store invocation details. Please try again"
}

asyncTriggerFailed

{
  "Message": "GE-1013 - Failed to invoke lambda asynchronously"
}