Images

POST /v1/images/generations

Text-to-image. Synchronous by default with a 30-second budget; add ?async=true for the async path (no time budget, precise failure codes).

Request body

OpenAI-standard fields plus Meshive extensions:

Field	Type	Default	Notes
model	string	required	The deployment’s model id
prompt	string	required
n	int	1	Images per request
size	string	"1024x1024"	Must be one of the model’s supported sizes — else 422 listing them
response_format	string	"url"	"url" | "b64_json"
negative_prompt	string	—	Meshive extension
seed	int	—	Meshive extension
steps	int	model default	Meshive extension — inference steps
guidance_scale	float	model default	Meshive extension
storage_credential_id	int	—	Meshive extension — output bucket override (storage)
webhook_url	string	—	Meshive extension — HTTPS callback on completion (webhooks)

Unknown OpenAI fields (style, quality, user, …) are ignored without error.

Query & headers

?async=true	Queue instead of waiting — returns 202 with a request id
Idempotency-Key header	Dedupes async submissions on retries (semantics)

Sync response

{
  "created": 1780000000,
  "data": [
    { "url": "https://...presigned..." }
  ]
}

Link and storage behavior depends on the output destination:

Destination	response_format=url	response_format=b64_json
Managed (default)	Link valid ~1 hour; the underlying object is removed shortly after — download promptly	Image returned inline; nothing stored
Your bucket (request override or deployment default)	Stored permanently; link signed ~7 days	Returned inline and stored in your bucket

Async response (202)

{
  "id": "req_9f8e7d6c5b4a3210",
  "object": "inference.request",
  "status": "queued",
  "modality": "image",
  "estimated_seconds": 30
}

Track it via GET /v1/requests/{id}, a webhook, or the console. Full guide: Async image generation.

Errors

Status · code	Meaning
404 model_not_found	Unknown model id
400 wrong_modality	The model isn’t an image model
422 size_not_supported	size not in the model’s list — message includes the supported sizes
422 invalid_webhook_url	webhook_url failed validation (must be public HTTPS)
422 (storage codes)	storage_credential_id unknown or not verified
429 replica_saturated	All replicas at concurrency limit — retry after Retry-After, or go async
503 no_pod_available	No replica ready (starting up, paused, or scaled away)
504 image_generation_timeout	Sync budget exceeded — use async
5xx upstream_error	GPU worker failed; most often memory. Async reports the exact cause
502 storage_upload_failed	Couldn’t write to your output bucket — check the credential

Note

Sync 5xx errors can’t name the exact cause (the worker’s logs aren’t visible on the sync path). If you need to know why — run the job with ?async=true and read error_code (e.g. vram_exceeded) on the request.

POST /v1/images/edits

Image-to-image editing, OpenAI-compatible (client.images.edit(...)). Multipart form:

Field	Type	Default	Notes
image	file	required	The input image
prompt	string	required
model	string	required	Must be an image model that accepts image input (I2I)
mask	file	—	Sync only — with ?async=true it returns 400 async_mask_unsupported
n	int	1
size	string	"1024x1024"	Validated against supported sizes
response_format	string	"url"
webhook_url	string	—	Meshive extension
storage_credential_id	int	—	Meshive extension

?async=true and Idempotency-Key work exactly as on generations; sync timeout returns 504 image_edit_timeout. Response shape, storage behavior, and the rest of the error table match generations (a model that doesn’t accept image input fails validate with 400).

curl

curl https://<your-deployment>.inference.meshive.ai/v1/images/edits \
  -H "Authorization: Bearer $MESHIVE_API_KEY" \
  -F image=@input.png \
  -F prompt="Make the sky a sunset" \
  -F model="<model-id>" \
  -F size="1024x1024"

Python

resp = client.images.edit(
    model="<model-id>",
    image=open("input.png", "rb"),
    prompt="Make the sky a sunset",
    size="1024x1024",
)
print(resp.data[0].url)