API reference

Images

Generate or edit images using a model that advertises the capability. Choose direct generation or the product queue according to the operation.

How it fits together

01Dispatch image generation and return a run reference
02Edit one or more uploaded images
03Generate images

Select an action to see its complete inputs, request, response, and status codes.

Dispatch image generation and return a run reference

POST/api/v1/chat/images/generations

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseMahvash product envelope

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`background`	Body	string	Optional	Conditional	auto, transparent, or opaque. Transparent needs png or webp.
`chat_id`	Body	string	Optional	Mahvash extension	Attach the generated image to an owned conversation.
`model`	Body	string	Optional	Supported	Public logical image model ID.
`moderation`	Body	string	Optional	Conditional	auto or low.
`n`	Body	integer	Optional	Conditional	Number of images, 1 to 10; above 1 needs route support.
`output_compression`	Body	integer	Optional	Conditional	Compression level 0 to 100 for lossy output formats.
`output_format`	Body	string	Optional	Conditional	png, jpeg, or webp.
`prompt`	Body	string	Required	Supported	Image prompt, up to 32,000 characters.
`quality`	Body	string	Optional	Conditional	auto, low, medium, high, standard, or hd.
`response_format`	Body	string	Optional	Conditional	b64_json or url. Mahvash always returns owned URLs.
`size`	Body	string	Optional	Conditional	auto or WIDTHxHEIGHT within the configured bounds.
`style`	Body	string	Optional	Conditional	vivid or natural, for routes that accept it.
`user`	Body	string	Optional	Supported	Provider abuse-monitoring user identifier.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/images/generations' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "prompt": "a red bicycle"
}'

Response

{
  "status": 0,
  "data": "<value>"
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
202	Dispatch image generation and return a run reference.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
503	A dependency is temporarily unavailable.

Edit one or more uploaded images

POST/v1/images/edits

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Content typemultipart/form-data

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`background`	Form	string	Optional	Conditional	auto, transparent, or opaque. Transparent needs png or webp.
`image`	Form	array<string> (binary)	Required	Supported	1 to 16 input images.
`input_fidelity`	Form	string	Optional	Conditional	low or high; rejected for models that always use high.
`mask`	Form	string (binary)	Optional	Supported	Alpha mask matching the first image's format and size.
`model`	Form	string	Optional	Supported	Public logical image model ID.
`moderation`	Form	string	Optional	Conditional	auto or low.
`n`	Form	integer	Optional	Conditional	Number of images, 1 to 10; above 1 needs route support.
`output_compression`	Form	integer	Optional	Conditional	Compression level 0 to 100 for lossy output formats.
`output_format`	Form	string	Optional	Conditional	png, jpeg, or webp.
`prompt`	Form	string	Required	Supported	Image prompt, up to 32,000 characters.
`quality`	Form	string	Optional	Conditional	auto, low, medium, high, standard, or hd.
`response_format`	Form	string	Optional	Conditional	b64_json or url. Mahvash always returns owned URLs.
`size`	Form	string	Optional	Conditional	auto or WIDTHxHEIGHT within the configured bounds.
`user`	Form	string	Optional	Supported	Provider abuse-monitoring user identifier.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/v1/images/edits' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Idempotency-Key: <unique-request-id>" \
  -F 'image=@./your-file' \
  -F 'prompt=a red bicycle'

Response

{
  "data": [
    {
      "url": "https://example.com/resource"
    }
  ],
  "created": 1750000000
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Edit one or more uploaded images.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
502	The selected provider returned an invalid or failed response.
503	A dependency is temporarily unavailable.

Generate images

POST/v1/images/generations

Production base URLhttps://api.mahvashai.ir

AuthenticationProject API key or user JWT

ResponseDirect OpenAI-style response

Content typeapplication/json

Parameters

The table shows the accepted inputs for this endpoint. Examples use placeholders and illustrate a safe integration pattern.

Name	Location	Type	Required	Support	Details
`Idempotency-Key`	Header	string	Optional	Supported	Replay key for an admitted run; a repeat returns the first result.
`X-Request-ID`	Header	string	Optional	Mahvash extension	Client-supplied correlation ID. Echoed on every response; replaced when absent or malformed.
`X-Mahvash-Project`	Header	string	Optional	Mahvash extension	Project slug or ID within the caller's organization. Narrows the request principal; it can never widen it.
`background`	Body	string	Optional	Conditional	auto, transparent, or opaque. Transparent needs png or webp.
`model`	Body	string	Optional	Supported	Public logical image model ID.
`moderation`	Body	string	Optional	Conditional	auto or low.
`n`	Body	integer	Optional	Conditional	Number of images, 1 to 10; above 1 needs route support.
`output_compression`	Body	integer	Optional	Conditional	Compression level 0 to 100 for lossy output formats.
`output_format`	Body	string	Optional	Conditional	png, jpeg, or webp.
`prompt`	Body	string	Required	Supported	Image prompt, up to 32,000 characters.
`quality`	Body	string	Optional	Conditional	auto, low, medium, high, standard, or hd.
`response_format`	Body	string	Optional	Conditional	b64_json or url. Mahvash always returns owned URLs.
`size`	Body	string	Optional	Conditional	auto or WIDTHxHEIGHT within the configured bounds.
`style`	Body	string	Optional	Conditional	vivid or natural, for routes that accept it.
`user`	Body	string	Optional	Supported	Provider abuse-monitoring user identifier.

A compatible model and provider route are required for conditional fields.

Request

curl -X POST 'https://api.mahvashai.ir/v1/images/generations' \
  -H "Authorization: Bearer $MAHVASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-request-id>" \
  -d '{
  "prompt": "a red bicycle"
}'

Response

{
  "data": [
    {
      "url": "https://example.com/resource"
    }
  ],
  "created": 1750000000
}

Illustrative response shape; actual fields depend on the operation and model.

Status codes

HTTP	Details
200	Generate images.
400	The request is not valid.
401	Authentication credentials are missing or invalid.
402	The account cannot authorize the request cost.
403	The principal is not allowed to perform this request.
404	No such resource is visible to this principal.
409	The requested transition conflicts with durable resource state.
429	A quota or rate limit was exceeded.
500	An internal error occurred.
502	The selected provider returned an invalid or failed response.
503	A dependency is temporarily unavailable.