Async requests

Model Gate async mode accepts an inference request and immediately returns a request ID. You can read the completed result through the Partner API or receive it at the callback configured in Profile. Processing continues independently of the original HTTP connection.

Async mode is supported for:

• POST /v1/chat/completions
• POST /v1/messages
• POST /v1/responses

Async requests cannot use stream: true.

Queue request

Add the Model Gate extension "async": true to an otherwise valid request.

Request

curl https://api.model-gate.com/v1/responses \
  -H "Authorization: Bearer mg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "Write a short release summary.",
    "async": true,
    "stream": false
  }'

Response — 202

{
  "request_id": "01KZ...",
  "status": "queued",
  "result_url": "https://p-api.model-gate.com/api/v1/requests/01KZ..."
}

The async field is a Model Gate option, not a parameter for the selected model. Model aliases resolve to their canonical models. Your key must remain eligible for execution, and the usual pricing and limits apply. Native async pricing does not use the batch request price coefficient.

An insufficient account balance or exhausted key/group spending limit can leave a request queued without consuming an execution attempt. A later top-up, usage reset or limit increase can make it eligible. There is no estimated-cost reservation: accepted work can finish with its complete actual cost, even when concurrent requests make the final balance negative or slightly exceed a spending limit. New executions are then blocked until the account is eligible again.

Recovery semantics

Native async provides at-least-once execution, not exactly-once execution. After an interruption, a request may be attempted again under the same Model Gate request ID even if the provider previously accepted it. Protection against duplicate billing does not make external tool actions exactly-once. Make application side effects idempotent. This generic async behavior is different from the dedicated Images protocol.

Retrieve result

Use a Partner API key belonging to the same Model Gate account.

Request

curl https://p-api.model-gate.com/api/v1/requests/01KZ... \
  -H "Authorization: Bearer mg_partner_..."

Response — processing

{
  "data": {
    "request_id": "01KZ...",
    "status": "processing",
    "created_at": "2026-08-05 10:00:00",
    "started_at": "2026-08-05 10:00:01",
    "completed_at": null,
    "expires_at": "2026-08-06 10:00:00"
  }
}

Response — completed

{
  "data": {
    "request_id": "01KZ...",
    "status": "completed",
    "response_status": 200,
    "response_headers": {
      "content-type": ["application/json"]
    },
    "response": {
      "id": "resp_...",
      "object": "response",
      "status": "completed"
    },
    "created_at": "2026-08-05 10:00:00",
    "started_at": "2026-08-05 10:00:01",
    "completed_at": "2026-08-05 10:00:03",
    "expires_at": "2026-08-06 10:00:00"
  }
}

The result endpoint returns the complete stored upstream body until expires_at. A foreign, expired, or unknown request ID returns 404.

Errors

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_async_stream_combination",
    "message": "Async requests cannot be streamed."
  }
}

Unsupported endpoints return async_not_supported.

Callbacks

Completed async results can be delivered to the callback configured in Profile, independently of further Model API requests. Callback retries can deliver the same event more than once. See Callbacks for signature verification, retries and idempotency guidance.

Images use a different queue

Do not send top-level async for Images. Use model_gate.async:true plus Idempotency-Key on the dedicated generation/edit endpoints. Poll /v1/images/operations, not Partner request results. Images do not automatically repeat a paid POST with an unknown outcome. A legacy Images request may return images_dedicated_api_required; check its existing result and contact Support before creating another intention, because that error does not prove no earlier work was performed. Audio transcription is available only through the dedicated transcription API, not this queue. An audio path executed through the generic queue is rejected with audio_dedicated_api_required; do not requeue it as a new paid intent.

Dedicated Video operations are not accepted by this generic queue. Use the JSON Video API with its own Idempotency-Key and operation history; an attempted legacy Video dispatch fails with video_dedicated_api_required before a supplier request. Video API.