Image Generation API

For shared conventions (base URL, authentication, response structure, rate limiting), see Authentication and Common Conventions.

Create an image

POST/v1/images/generations

Authentication

Authorization: Bearer <API_KEY>, using a platform API key created on the console's "API Keys" page.

Request body · application/json

Prop

Type

Image models have different limits on size, count, and return format; first confirm with /v1/models, and rely on the parameter validation errors returned by the API.

First use /v1/models to confirm the image model ID available to the current key, then replace model with it. size must be within the tiers supported by that model — minimum pixel counts vary widely between models, and an invalid value returns a parameter error directly rather than being silently downgraded.

The response may be in URL form or Base64 form, depending on the model and channel.

Request

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "白色桌面上的一个红苹果，柔和自然光，产品摄影",
  "size": "当前模型支持的尺寸",
  "n": 1
}
JSON

Response parameters

Parameter	Type	Description
`created`	integer	Generation time (Unix seconds)
`model`	string	Some models return the model ID that was actually executed
`data`	array	List of generation results
`data[].url`	string	Image URL; present when the response is in URL form, and may be a short-lived signed URL
`data[].b64_json`	string	Base64 image data; present when the response is in Base64 form
`data[].size`	string	Some models return the actual generated size
`size`	string	Actual generated size at the top level, for example `1024x1024`, `1376x768`
`quality`	string	Actual quality tier at the top level, for example `auto`, `low`
`output_format`	string	Actual output format at the top level, for example `png`
`background`	string	Background handling at the top level, for example `auto`, `opaque`
`moderation`	string	Content moderation tier at the top level; returned by some models
`usage`	object	Image usage; image-to-image also counts input image tokens

A single request may return only url or only b64_json, depending on the model and channel; rely on the actual returned fields, and when both are present, prefer url.

Response body

Returning a URL (url form):

{
  "created": 1789567052,
  "data": [
    {
      "size": "2048x2048",
      "url": "https://media.example.com/image-public-id.jpeg"
    }
  ],
  "model": "Doubao-Seedream-4.5"
}

Returning Base64 (b64_json form, excerpt):

{
  "background": "auto",
  "created": 1789071752,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ]
}

URLs returned in url form may be short-lived signed URLs, so copy them to your own storage or record them promptly; decode b64_json form yourself and store it properly. Do not assume all image models accept response_format or the same sizes. Observed: gpt-image-1-mini rejects response_format, and Doubao-Seedream-4.5 currently requires images of at least 3686400 pixels — 2048x2048 is accepted while 1024x1024 returns a parameter error.

Error response

{
  "error": {
    "message": "当前图片模型不支持请求的尺寸",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "size"
  }
}

HTTP	Response / Cause	Handling
`400`	`Model name not specified, model name cannot be empty`	Request body is missing `model`
`400`	`invalid_parameter` (`param=size`)	Use a size supported by the current model
`400`	`unknown_parameter` (`param=response_format`)	Remove this field and use the model's default return format
`400`	`InvalidParameter` / `upstream_error`	The upstream model rejected the size, pixel count, or other parameters; adjust according to `message`
`400`	`invalid_parameter` (`param=n`)	Change to `n=1`
`400`	`image is required` (`code=convert_request_failed`)	The image-to-image request did not include a reference image; add `image` as shown in the example below
`400`	`n must be an integer between 1 and 128` (`code=invalid_request`)	`n` is out of range; change it to `1`–`128`
`429`	`credit_balance_exhausted` / `insufficient_quota`	The current channel has insufficient balance; switch to another available channel or contact platform support
`401`	`Invalid token`	API key missing, incorrect, or expired
`500`	`{"error":{"code":"convert_request_failed","message":"not supported model for image generation, only imagen models are supported"}}`	The current model does not support the image generation API; switch to an image model that supports it
`503`	`model_not_found` / `No available channel`	The current group has no available channel for this model; choose a model of the same kind

For the complete explanation, see Error Codes and Troubleshooting.

Image-to-image (image editing)

POST/v1/images/edits

Generate a new image based on an existing one: upload one or more reference images, and the model rewrites the scene, changes the style, or performs local inpainting according to prompt.

Request body · multipart/form-data

Prop

Type

The request must include a reference image; without one, the API returns a parameter error directly and never reaches the model.

Request example

Image-to-image uses multipart/form-data; submit each field with -F, not -d. Upload the reference image with image=@file-path.

When you need multiple reference images, write the field as an array, image[], and repeat it. There is no JSON request body here; Content-Type is set automatically by curl -F, so do not set it manually.

Image-to-image

curl -X POST "https://locopalai.com/v1/images/edits" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -F "model=从 /v1/models 选择的图片模型 ID" \
  -F "prompt=把这张照片改成柔和的水彩画风格" \
  -F "size=1024x1024" \
  -F "image=@./reference.png"

Repeat the field for multiple reference images:

  -F "image[]=@./reference-a.png" \
  -F "image[]=@./reference-b.png"

Response body

Same structure as Create an image, with the image returned as b64_json or url:

{
  "background": "opaque",
  "created": 1789651524,
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU..." }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 1041,
    "input_tokens_details": { "image_tokens": 1032, "text_tokens": 9 },
    "output_tokens": 439,
    "total_tokens": 1480
  }
}

usage.input_tokens_details.image_tokens reflects the consumption of reference images: the more reference images or the larger they are, the higher the input tokens.

Passing reference images via public URLs

Models that support reference image input can also pass them via images in the JSON request body of POST /v1/images/generations, where each element is a public https:// image URL:

curl -X POST "https://locopalai.com/v1/images/generations" \
  -H "Authorization: Bearer $LOCOPAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "从 /v1/models 选择的图片模型 ID",
  "prompt": "把这张照片改成柔和的水彩画风格",
  "images": ["https://example.com/reference.png"]
}
JSON

Reference images must be directly downloadable by the server; if a URL is invalid or requires login, the request ends with an upstream download error. The response structure is the same as Create an image.

Relationship with the asset library

Generated images do not automatically enter the asset library. If a later video task needs an image as a reference image, first add it to the library using the Asset Library API and poll until it is Active, then reference it with asset://<asset_id>.

On this page