Skip to main content

OpenAI Chat Completions reference

POST /v1/chat/completions: request fields, responses and streaming.

Endpoint and prerequisites

POST https://acosmi.com/v1/chat/completions

Authenticate using a personal PAYG key with Authorization: Bearer and models:chat scope. The compatibility surface and selected openai profile must be available, with confirmed pricing, finance and release state in the catalog. Protocol compatibility does not imply every vendor API is supported.

Request fields

FieldTypeUsage
modelstringSelected profile UUID, not the display name
messagesarrayAt least one message in this protocol’s format
max_tokensintegerExplicit positive value within the profile output limit; this example uses 64
streambooleanfalse for JSON, true for SSE
temperature / top_pnumberSend only if declared; model-specific ranges apply
tools / tool_choicearray / string or objectOnly for supported configurations; protocol-specific shapes
acosmi_optionsobjectAcosmi extensions for V2 price version and spending cap, as described below

Use protocol roles such as system, user and assistant in messages. Read text from choices[].message.content and tool calls from choices[].message.tool_calls.

Follow supported_parameters on the model detail page. Current public text profiles declare max_tokens. Budget support differs across entry points; do not substitute max_completion_tokens or send both without confirming the endpoint contract.

V2 request template

Use this only with an available TEXT_COMPONENTS_V2 configuration. Provide its current positive price-version integer. A CNY 1 cap is the public Credits string "1000000".

sh
: "${ACOSMI_API_KEY:?Set your personal PAYG key}"
: "${ACOSMI_MODEL_ID:?Set a callable V2 OpenAI profile UUID}"
: "${ACOSMI_PRICE_VERSION:?Set its current positive effective_price_version}"
curl --fail-with-body 'https://acosmi.com/v1/chat/completions' \
  -H "Authorization: Bearer $ACOSMI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{"model":"$ACOSMI_MODEL_ID","messages":[{"role":"user","content":"Hello"}],"max_tokens":64,"stream":false,"acosmi_options":{"contract_version":"TEXT_COMPONENTS_V2","expected_price_version":${ACOSMI_PRICE_VERSION},"max_credits":"1000000"}}
JSON

acosmi_options is not sent to the model vendor. A price-version change requires another decision, not an automatic budget increase. Legacy V1 total-token requests do not use these V2 fields; copy the template for the selected configuration.

Successful response

This abbreviated structure is illustrative, not a production receipt. Usage numbers demonstrate fields only:

json
{"choices":[{"message":{"role":"assistant","content":"Hello!"},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}

Handle delivered output, stop reasons and financial status separately. A tool request is not an executed tool: validate the name and arguments, perform the authorized action, and return its result in the proper protocol. See tools and structured output.

Streaming and errors

With stream=true, consume text/event-stream. OpenAI streams use choices[].delta and finish normally with [DONE]. Heartbeats, errors and disconnections are not normal completion. See streaming.

Inspect the protocol error object for non-2xx responses. After streaming has begun, errors may appear inside events despite HTTP 200. Keep request IDs and follow error handling before repeating a request.

Models · Authentication · Billing · OpenAPI