API overview

The Meshive inference API is OpenAI-compatible: point any OpenAI SDK at your deployment’s endpoint URL and your code works unchanged — including streaming.

Base URL

Every serving deployment gets its own endpoint:

https://<your-deployment>.inference.meshive.ai/v1

Copy the exact URL from the deployment’s card on the Serving page. There is no shared global endpoint — requests to anything but your deployment URL return 404.

One deployment serves one model, so the SDK’s model parameter is optional on chat/completions/embeddings: leave it empty and the endpoint fills in its own model. If you pass one, it must match the deployment’s model id (else 400).

from openai import OpenAI

client = OpenAI(
    base_url="https://<your-deployment>.inference.meshive.ai/v1",
    api_key="mk-...",
)

Authentication

Authorization: Bearer mk-...

Workspace API keys are managed on the Models page → API Keys (guide). A key works against every deployment in its workspace.

Endpoints

Endpoint	Purpose
`POST /v1/chat/completions`	Chat (streaming supported)
`POST /v1/completions`	Text completion (streaming supported)
`POST /v1/embeddings`	Embeddings
`GET /v1/models`	The model this endpoint serves
`POST /v1/images/generations`	Image generation — sync (30s budget) or `?async=true`
`POST /v1/images/edits`	Image editing (multipart)
`POST /v1/videos` · `POST /v1/videos/generations`	Video generation — always async
`GET /v1/videos/{id}`	Video status / download / cancel
`GET /v1/requests`	Track and cancel async requests

OpenAI compatibility

Response schemas match OpenAI, for both streaming and non-streaming.
Unknown parameters never error. On text endpoints, extra OpenAI fields (tools, response_format, seed, logprobs, …) are passed through to the inference engine; on image endpoints, unsupported OpenAI fields are ignored. Either way, existing OpenAI code runs as-is.
Meshive extensions are explicit, additive fields — e.g. negative_prompt, steps, webhook_url, storage_credential_id on media endpoints.

Errors

All errors share one envelope:

{
  "error": {
    "message": "Size '2048x2048' not in supported ['1024x1024'].",
    "type": "invalid_request_error",
    "code": "size_not_supported",
    "documentation_url": "https://docs.meshive.ai/serverless/async-images"
  }
}

code and documentation_url appear when available. Validation errors include the valid alternatives in message whenever the API knows them (supported sizes, resolutions, fps, …).

Status codes

Status	When
`400`	Invalid request — wrong modality for the endpoint, `model` doesn’t match the deployment, malformed input
`401`	Missing/invalid/expired API key
`402`	Workspace credit exhausted — top up to resume
`403`	The resource belongs to another workspace
`404`	Unknown model/request id — or a URL that isn’t a deployment endpoint
`409`	Conflict with current state — e.g. canceling a request that’s already `running`
`422`	Validation failed — unsupported size/resolution, bad `webhook_url`, unverified storage credential
`429`	Rate limit (text endpoints) or replica saturation (image sync) — includes `Retry-After`
`502`	Result couldn’t be uploaded to your output bucket (`storage_upload_failed`)
`503`	Deployment paused or no replica ready
`504`	Sync image generation exceeded the 30s budget — use async

Rate limits

Two independent mechanisms:

Per-key RPM / TPD — applies to chat/completions, completions, and embeddings. Defaults: 60 requests/min and 1,000,000 tokens/day per key (configurable per key at creation). Successful responses include X-RateLimit-Remaining and X-RateLimit-Reset; exceeding a limit returns 429 (rate_limit_error) with Retry-After.
Replica saturation — synchronous image requests return 429 (replica_saturated, Retry-After: 5) when every replica is at its concurrency limit. Switch to ?async=true (queued, not rejected) or let autoscaling add replicas.

Idempotency

Async submissions (/v1/images/generations?async=true, /v1/images/edits?async=true, /v1/videos, /v1/videos/generations) accept an Idempotency-Key header. Re-sending the same key on the same API key returns the original request instead of creating a duplicate. Always set it when you have retry logic.