> ## Documentation Index > Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Edit images > Request format, responses, and capability boundaries. `POST /v1/images/edits` Start with multipart upload: `model`, `prompt`, `image`, and optional `mask`. Let the SDK/cURL generate the boundary; use repeated `image[]` when required by a multi-image channel. The JSON schema describes `images[].image_url` only for channels supporting that form; other plugins can differ. Confirm mask semantics, reference count, formats, and sizes for the model. The generic Files API is unimplemented; there is no universal file\_id upload workflow. [Integration guide and runnable example](/en/guides/image-generation) [简体中文](/zh/api-reference/images-edits) ## OpenAPI ````yaml openapi/relay.json POST /v1/images/edits openapi: 3.0.3 info: title: API — Core inference API version: 0.5.0 description: >- 面向接入的精选规范，不是全部管理或供应商接口。 / Curated integration specification, not the entire management or provider API. license: name: AGPL-3.0-or-later servers: - url: https://gateway.example.com description: >- Example only; replace with your gateway origin and optional path prefix, without /v1. security: - BearerAuth: [] paths: /v1/images/edits: post: summary: 编辑图片 / Edit images description: >- 常用接入字段；能力取决于模型、渠道与部署。 / Common integration fields; support depends on the model, channel, and deployment. operationId: POSTImagesEdits requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/ImageEditMultipart' application/json: schema: $ref: '#/components/schemas/ImageEditJSON' responses: '200': description: 图片结果 / Image result content: application/json: schema: $ref: '#/components/schemas/ImageResult' example: created: 1700000000 data: - url: https://cdn.example.com/image.png '400': description: 请求参数错误 / Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: 身份校验失败 / Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 访问被拒绝 / Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: 接口或资源不存在 / Endpoint or resource not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: 请求被限流或受配额限制 / Rate or quota restriction content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: 网关或上游错误 / Gateway or upstream error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: 服务暂不可用 / Service unavailable content: application/json: schema: $ref: '#/components/schemas/Error' '504': description: 等待任务超时；工作仍可能继续 / Timed out waiting; work may continue content: application/json: schema: $ref: '#/components/schemas/Error' default: description: 其他网关或上游错误；格式可能不同 / Other gateway or upstream error; shape may vary content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ImageEditMultipart: type: object properties: model: type: string description: >- 当前密钥可用且支持此接口的模型 ID / Model ID available to the key and supporting this endpoint example: YOUR_MODEL_ID prompt: type: string description: >- 任务描述；遵循模型的长度和内容要求 / Task description; follow model length and content requirements 'n': type: integer description: >- 请求图片数，模型通常有更小限制；建议从 1 开始 / Requested image count; models usually impose a smaller limit; start with 1 minimum: 1 maximum: 128 size: type: string description: 模型支持的尺寸，使用 x 而不是 × / Model-supported size; use x rather than × quality: type: string description: 质量档位，由模型决定 / Quality setting determined by the model response_format: type: string description: >- url 或 b64_json，仅在模型支持时指定；有些模型固定返回 Base64 / url or b64_json when supported; some models always return Base64 output_format: type: string description: >- 输出编码，例如 png、jpeg、webp；需模型支持 / Output encoding such as png, jpeg, webp; requires model support background: type: string description: >- 背景选项；透明背景需模型和编码支持 / Background option; transparency requires model and format support image: type: string description: >- 输入图片文件；重复 image[] 的支持取决于渠道 / Input image file; repeated image[] support depends on the channel format: binary mask: type: string description: >- 可选蒙版；格式、尺寸与透明区域语义由模型决定 / Optional mask; format, dimensions, and transparent-area semantics depend on the model format: binary required: - model - prompt - image ImageEditJSON: type: object properties: model: type: string description: >- 当前密钥可用且支持此接口的模型 ID / Model ID available to the key and supporting this endpoint example: YOUR_MODEL_ID prompt: type: string description: >- 任务描述；遵循模型的长度和内容要求 / Task description; follow model length and content requirements 'n': type: integer description: >- 请求图片数，模型通常有更小限制；建议从 1 开始 / Requested image count; models usually impose a smaller limit; start with 1 minimum: 1 maximum: 128 size: type: string description: 模型支持的尺寸，使用 x 而不是 × / Model-supported size; use x rather than × quality: type: string description: 质量档位，由模型决定 / Quality setting determined by the model response_format: type: string description: >- url 或 b64_json，仅在模型支持时指定；有些模型固定返回 Base64 / url or b64_json when supported; some models always return Base64 output_format: type: string description: >- 输出编码，例如 png、jpeg、webp；需模型支持 / Output encoding such as png, jpeg, webp; requires model support background: type: string description: >- 背景选项；透明背景需模型和编码支持 / Background option; transparency requires model and format support images: type: array description: >- 模型支持时使用 URL 引用；不是所有渠道的通用格式 / URL references when supported; not a universal format across channels items: type: object properties: image_url: type: string description: HTTPS 或 data URL / HTTPS or data URL required: - image_url required: - model - prompt - images ImageResult: type: object properties: created: type: integer description: Unix 秒 / Unix seconds data: type: array description: >- 检查每项的 url 或 b64_json，不能仅凭 HTTP 200 判断有图片 / Check url or b64_json in each item; HTTP 200 alone does not guarantee an image items: type: object properties: url: type: string description: >- 可能短期有效；不要向此 URL 发送网关密钥 / May expire; never send the gateway key to this URL b64_json: type: string description: 图片字节的 Base64，不是 data URL / Base64 image bytes, not a data URL revised_prompt: type: string description: 可选改写提示词 / Optional revised prompt required: - data Error: type: object properties: error: type: object properties: message: type: string type: type: string param: type: string nullable: true code: nullable: true description: 错误标识；类型随上游变化 / Error identifier; type varies by upstream securitySchemes: BearerAuth: type: http scheme: bearer description: 模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.