OpenAI compatible API
Machines are in beta. The OpenAI compatible routes can change before general availability.
Each saved Machine is also a model of an OpenAI compatible API. A chat completion with the model machine/<name> runs the Machine. A tool call of the Machine comes back as an OpenAI tool_call, and your code sends the result as a tool message. Use these routes when you want only the runtime, and you run the tools in your own code.
The routes are not in the CloudRaker SDK. Use an OpenAI SDK.
Each route needs the scope machines. A run of this API is a run of Machines, with the same billing and limits.
Set up the client
Set the base URL of the SDK to the API of your organization, and use an API key as the OpenAI key.
Models
A model id is machine/<name> (the published version) or machine/<name>@<version>. An unknown id gives 404 model_not_found. The id can be raw or URL-encoded in the path of GET /v2/models/{model}.
machine.caller_tools lists the tools that your code runs. machine.pseudo_tools holds the schemas of the pseudo tools.
Run a Machine
The client sends the full history on each request. The history carries the state of the run in the tool call ids, so the API needs no session.
The inputs of a new run
A request with no tool call id of a run starts a new run. The API gets the inputs in this order:
machine_inputs, when the request has it.- Else the first
usermessage, when its text is a JSON object whose keys are all inputs of the Machine. - Else the text of the last
usermessage is the inputuser_message, when the Machine declares it.
The file parts (file_id or file_data) and the image_url parts (https or data:) of the user messages become the file inputs f1, f2 and so on, in order. On this route only, a file can be base64 data. The API ignores system and developer messages. A required input that is missing gives 400 inputs_required with the names.
Send a tool result
For each tool call of your tools, send a tool message with the same tool_call_id:
- JSON content is the output. Other content is a string output.
{"error": {"code": "vendor_not_found", "message": "…"}}is an error output. Acodefrom thex-errorsof the tool matches anon_errorcase of the step.- An output that does not match the output schema of the tool gives a
400error, and the call stays pending.
A resend of the same history is safe. The run ignores a result that it already took, and the answer shows the current state of the run.
Idempotency
Only an Idempotency-Key header makes a new run idempotent. With no key, two equal first requests start two runs, as in OpenAI. The continuation requests are idempotent by the tool call ids. Read Idempotency.
Pseudo tools
A run can stop for something other than a tool of your code. The API then sends a tool call of a reserved pseudo tool. A Machine cannot have a tool with the prefix machine_.
A trailing user message with no tool message is the input of a machine_input call. When the run waits for a tool output or a person, it gives 400 tool_output_required with the pending id.
The answer
- A failed run answers HTTP
200with a refusal, not an error. The request was valid. idis the same for the same state of the run.system_fingerprintisbm-ir/1:and the first 12 hex digits of the hash of the compiled program.usagecounts the tokens of the exception model since the previous answer. Addusageover your calls to get the total of the run.machine.creditsis 0 until the run ends.- The
x-machine-runheader holds the run id. Read the run withGET /v2/machines/runs/{id}.
Waits
The API waits for the next stop of the run, at most 300 seconds. It does not read Prefer. When the run does not stop in that time, the answer is a machine_wait tool call.
stream: true is not available. It gives 400 unsupported_parameter.
Request fields
The API reads no notify, deadline or metadata of this body.
Errors
The OpenAI compatible routes answer errors in the OpenAI shape, with the x-request-id header:
type comes from the status: 400 and 409 give invalid_request_error, 401 authentication_error, 402 insufficient_quota, 403 permission_error, 404 not_found_error, 429 rate_limit_error and 5xx api_error.
code is a code of API v2, or one of the codes in OpenAI route errors.