Artgen API Reference

Authenticate with a dashboard API key and call Artgen from your server — models, styles, create, and convert.

Send requests to https://artgen.net, not to this docs site. Create a key on Dashboard → API Keys while signed in, then send it only from your server.

These pages describe the current HTTP contract. Choose modelId and styleId from the live catalogs; do not invent identifiers.

Authentication

POST /api/create and POST /api/convert require an API key. GET /api/models and GET /api/styles do not.

Send the secret with either header:

Authorization: Bearer $ARTGEN_API_KEY

or:

x-api-key: $ARTGEN_API_KEY

Rules:

A login cookie does not authenticate /api/create or /api/convert.
An API key does not authenticate account, dashboard, or admin routes.
If both headers are present, they must carry the same key. A malformed Authorization value (including a non-Bearer scheme), a key that contains whitespace or commas, or two different keys, is rejected.
Store the secret on your server. Do not put it in browser frontend code, public repositories, prompts, URLs, screenshots, or logs.

Create and manage keys in Dashboard → API Keys: name the key (1–32 characters), choose 30 / 90 / 365 days or no expiration (the dashboard default is 90 days), and copy the secret once. The full value is shown only at creation and is stored hashed. You can rename, disable, enable (unless expired), or revoke a key. Expired keys cannot be re-enabled. “Last used” is the most recent successful authentication, not a successful image generation.

GET /api/models

Lists published models. No API key. The response is not cached (Cache-Control: no-store).

curl --silent --show-error --include --proto '=https' \
  'https://artgen.net/api/models'

Require HTTP 200 and JSON. Do not follow redirects (-L) or treat an HTML page as success.

200

{
  "models": [
    {
      "id": "published-model-id",
      "name": "Display name",
      "description": "Public description",
      "supportsText": true,
      "supportsTransfer": false,
      "supportsInlineOutput": true,
      "sizes": [{ "value": "1024x1024", "label": "1:1" }],
      "maxPromptLength": 1600,
      "sourceImageMaxDimension": 511
    }
  ]
}

Field	Meaning
`id`	Send this as `modelId`. It is the public catalog id, not a provider’s internal name.
`name`, `description`	Display metadata.
`supportsText`	Must be `true` for `POST /api/create`.
`supportsTransfer`	Must be `true` for `POST /api/convert`.
`supportsInlineOutput`	Whether the model can return image data returned directly in the response that satisfies `requireInlineOutput: true`.
`sizes`	Allowed canvas values. Send a `value`, not the `label`. Values may be dimensions or aspect ratios depending on the model.
`maxPromptLength`	Maximum length of the user `prompt`.
`sourceImageMaxDimension`	Present only on some models. When present, both edges of a convert source image must be at most this many pixels.

500 — { "error": "server_error" } if the catalog cannot be loaded.

GET /api/styles

Lists every style in the catalog. No API key. Not paginated. Internal style prompts are omitted. The response is not cached (Cache-Control: no-store).

curl --silent --show-error --include --proto '=https' \
  'https://artgen.net/api/styles'

Optional query: locale (en or zh-CN). Omitted locale defaults to en. Any other value returns 400 { "error": "invalid_locale" }.

200

{
  "styles": [
    {
      "id": "style-id",
      "dimension": "2d",
      "name": "Style name",
      "description": "Public description"
    }
  ]
}

Field	Meaning
`id`	Pass this exact value as `styleId`, or omit `styleId`.
`dimension`	`2d` or `3d`. `3d` is a visual treatment of a raster image, not a mesh or 3D file export.
`name`, `description`	Localized labels for the requested `locale`.

POST /api/create

Text-to-image. The server sets mode to text. Requires a published model with supportsText.

Headers: Authorization: Bearer … or x-api-key, and Content-Type: application/json.

Body fields (unknown keys are rejected):

Field	Required	Rules
`modelId`	yes	A published `id` from `GET /api/models`.
`prompt`	yes	Nonempty string after trim; length at most the model’s `maxPromptLength`.
`styleId`	no	An `id` from `GET /api/styles`.
`size`	no	A `sizes[].value` from the selected model. If omitted, the model’s size whose `label` is `1:1` is used; if that size is missing, the request is invalid.
`mode`	no	If present, must be `text`. Conflicting values are rejected.
`requireInlineOutput`	no	Boolean. `true` is accepted only when the model has `supportsInlineOutput`.
`sourceImage`	no	Must be omitted. Sending a source image on create is rejected.

curl --silent --show-error --include --proto '=https' \
  --request POST \
  --header "Authorization: Bearer $ARTGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"modelId":"id-from-models","prompt":"A quiet mountain lake at sunrise, watercolor"}' \
  'https://artgen.net/api/create'

POST /api/convert

Reference-image conversion. The server sets mode to transfer. Requires a published model with supportsTransfer.

Headers: same as create.

Body fields (unknown keys are rejected):

Field	Required	Rules
`modelId`	yes	A published `id` from `GET /api/models` with `supportsTransfer`.
`prompt`	yes	Same prompt rules as create.
`sourceImage`	yes	A PNG, JPEG, or WebP base64 data URL (`data:image/png;base64,…`, `data:image/jpeg;base64,…`, or `data:image/webp;base64,…`). Decoded payload at most 5 MiB (5,242,880 bytes). The bytes must match the declared type. Remote image URLs and multipart uploads are rejected. When the model lists `sourceImageMaxDimension`, both pixel edges must be at most that value.
`styleId`	no	An `id` from `GET /api/styles`.
`size`	no	Same default as create (`label` `1:1`).
`mode`	no	If present, must be `transfer`.
`requireInlineOutput`	no	Same rule as create.

curl --silent --show-error --include --proto '=https' \
  --request POST \
  --header "Authorization: Bearer $ARTGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"modelId":"id-from-models","prompt":"A quiet mountain lake at sunrise, watercolor","sourceImage":"data:image/png;base64,..."}' \
  'https://artgen.net/api/convert'

Success response

Create and convert share this success shape. width and height are included only when the model returns them.

{
  "success": true,
  "requestId": "uuid",
  "data": {
    "imageUrl": "data:image/jpeg;base64,...",
    "model": "Display name",
    "modelId": "published-model-id"
  }
}

imageUrl is either a base64 data URL or an HTTPS image URL. Treat it as private. Generation responses send X-Request-Id (same value as requestId) and Cache-Control: no-store.

There is no idempotency key, job id, or status endpoint. Each POST is a new request. A request id is for support correlation, not retry deduplication.

Errors

Create and convert errors return { "error": "<code>", "requestId": "<uuid>" } with X-Request-Id and Cache-Control: no-store. Catalog errors use only { "error": "<code>" }.

HTTP	`error`	When
`400`	`invalid_request`	Invalid JSON, unknown fields, wrong `mode`, missing or empty `prompt`, unknown `modelId` / `styleId` / `size`, a model that does not support the endpoint, a convert source that is not an accepted data URL, `requireInlineOutput` that the model cannot satisfy, or a composed prompt the model rejects.
`400`	`invalid_locale`	`GET /api/styles` with a `locale` other than `en` or `zh-CN`.
`401`	`unauthorized`	Missing, malformed, mismatched, unknown, disabled, revoked, or expired key; or a key whose owner no longer exists.
`403`	`forbidden`	The key owner is banned (and the ban has not expired) or the owner’s email is not verified.
`402`	`insufficient_credits`	The account cannot run this request.
`429`	`rate_limited`	The key was rate-limited or its configured usage was exceeded.
`503`	`provider_unavailable`	The selected model’s provider is not available or not configured.
`502`	`generation_failed`	The provider call failed after the request was accepted.
`500`	`generation_failed`	An unexpected server failure during generation.
`500`	`server_error`	`GET /api/models` could not load the catalog.

Record the HTTP status and requestId when asking for help. Do not send the API key, prompt, raw request body, or raw image in support mail.

Create a key: Dashboard → API Keys
Model guides: How to choose a model

Send requests to https://artgen.net, not to this docs site. Create a key on Dashboard → API Keys while signed in, then send it only from your server.

These pages describe the current HTTP contract. Choose modelId and styleId from the live catalogs; do not invent identifiers.

Authentication

POST /api/create and POST /api/convert require an API key. GET /api/models and GET /api/styles do not.

Send the secret with either header:

Authorization: Bearer $ARTGEN_API_KEY

or:

x-api-key: $ARTGEN_API_KEY

Rules:

A login cookie does not authenticate /api/create or /api/convert.
An API key does not authenticate account, dashboard, or admin routes.
If both headers are present, they must carry the same key. A malformed Authorization value (including a non-Bearer scheme), a key that contains whitespace or commas, or two different keys, is rejected.
Store the secret on your server. Do not put it in browser frontend code, public repositories, prompts, URLs, screenshots, or logs.

GET /api/models

Lists published models. No API key. The response is not cached (Cache-Control: no-store).

curl --silent --show-error --include --proto '=https' \
  'https://artgen.net/api/models'

Require HTTP 200 and JSON. Do not follow redirects (-L) or treat an HTML page as success.

200

{
  "models": [
    {
      "id": "published-model-id",
      "name": "Display name",
      "description": "Public description",
      "supportsText": true,
      "supportsTransfer": false,
      "supportsInlineOutput": true,
      "sizes": [{ "value": "1024x1024", "label": "1:1" }],
      "maxPromptLength": 1600,
      "sourceImageMaxDimension": 511
    }
  ]
}

Field	Meaning
`id`	Send this as `modelId`. It is the public catalog id, not a provider’s internal name.
`name`, `description`	Display metadata.
`supportsText`	Must be `true` for `POST /api/create`.
`supportsTransfer`	Must be `true` for `POST /api/convert`.
`supportsInlineOutput`	Whether the model can return image data returned directly in the response that satisfies `requireInlineOutput: true`.
`sizes`	Allowed canvas values. Send a `value`, not the `label`. Values may be dimensions or aspect ratios depending on the model.
`maxPromptLength`	Maximum length of the user `prompt`.
`sourceImageMaxDimension`	Present only on some models. When present, both edges of a convert source image must be at most this many pixels.

500 — { "error": "server_error" } if the catalog cannot be loaded.

GET /api/styles

Lists every style in the catalog. No API key. Not paginated. Internal style prompts are omitted. The response is not cached (Cache-Control: no-store).

curl --silent --show-error --include --proto '=https' \
  'https://artgen.net/api/styles'

Optional query: locale (en or zh-CN). Omitted locale defaults to en. Any other value returns 400 { "error": "invalid_locale" }.

200

{
  "styles": [
    {
      "id": "style-id",
      "dimension": "2d",
      "name": "Style name",
      "description": "Public description"
    }
  ]
}

Field	Meaning
`id`	Pass this exact value as `styleId`, or omit `styleId`.
`dimension`	`2d` or `3d`. `3d` is a visual treatment of a raster image, not a mesh or 3D file export.
`name`, `description`	Localized labels for the requested `locale`.

POST /api/create

Text-to-image. The server sets mode to text. Requires a published model with supportsText.

Headers: Authorization: Bearer … or x-api-key, and Content-Type: application/json.

Body fields (unknown keys are rejected):

Field	Required	Rules
`modelId`	yes	A published `id` from `GET /api/models`.
`prompt`	yes	Nonempty string after trim; length at most the model’s `maxPromptLength`.
`styleId`	no	An `id` from `GET /api/styles`.
`size`	no	A `sizes[].value` from the selected model. If omitted, the model’s size whose `label` is `1:1` is used; if that size is missing, the request is invalid.
`mode`	no	If present, must be `text`. Conflicting values are rejected.
`requireInlineOutput`	no	Boolean. `true` is accepted only when the model has `supportsInlineOutput`.
`sourceImage`	no	Must be omitted. Sending a source image on create is rejected.

curl --silent --show-error --include --proto '=https' \
  --request POST \
  --header "Authorization: Bearer $ARTGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"modelId":"id-from-models","prompt":"A quiet mountain lake at sunrise, watercolor"}' \
  'https://artgen.net/api/create'

POST /api/convert

Reference-image conversion. The server sets mode to transfer. Requires a published model with supportsTransfer.

Headers: same as create.

Body fields (unknown keys are rejected):

Field	Required	Rules
`modelId`	yes	A published `id` from `GET /api/models` with `supportsTransfer`.
`prompt`	yes	Same prompt rules as create.
`sourceImage`	yes	A PNG, JPEG, or WebP base64 data URL (`data:image/png;base64,…`, `data:image/jpeg;base64,…`, or `data:image/webp;base64,…`). Decoded payload at most 5 MiB (5,242,880 bytes). The bytes must match the declared type. Remote image URLs and multipart uploads are rejected. When the model lists `sourceImageMaxDimension`, both pixel edges must be at most that value.
`styleId`	no	An `id` from `GET /api/styles`.
`size`	no	Same default as create (`label` `1:1`).
`mode`	no	If present, must be `transfer`.
`requireInlineOutput`	no	Same rule as create.

curl --silent --show-error --include --proto '=https' \
  --request POST \
  --header "Authorization: Bearer $ARTGEN_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"modelId":"id-from-models","prompt":"A quiet mountain lake at sunrise, watercolor","sourceImage":"data:image/png;base64,..."}' \
  'https://artgen.net/api/convert'

Success response

Create and convert share this success shape. width and height are included only when the model returns them.

{
  "success": true,
  "requestId": "uuid",
  "data": {
    "imageUrl": "data:image/jpeg;base64,...",
    "model": "Display name",
    "modelId": "published-model-id"
  }
}

imageUrl is either a base64 data URL or an HTTPS image URL. Treat it as private. Generation responses send X-Request-Id (same value as requestId) and Cache-Control: no-store.

There is no idempotency key, job id, or status endpoint. Each POST is a new request. A request id is for support correlation, not retry deduplication.

Errors

Create and convert errors return { "error": "<code>", "requestId": "<uuid>" } with X-Request-Id and Cache-Control: no-store. Catalog errors use only { "error": "<code>" }.

HTTP	`error`	When
`400`	`invalid_request`	Invalid JSON, unknown fields, wrong `mode`, missing or empty `prompt`, unknown `modelId` / `styleId` / `size`, a model that does not support the endpoint, a convert source that is not an accepted data URL, `requireInlineOutput` that the model cannot satisfy, or a composed prompt the model rejects.
`400`	`invalid_locale`	`GET /api/styles` with a `locale` other than `en` or `zh-CN`.
`401`	`unauthorized`	Missing, malformed, mismatched, unknown, disabled, revoked, or expired key; or a key whose owner no longer exists.
`403`	`forbidden`	The key owner is banned (and the ban has not expired) or the owner’s email is not verified.
`402`	`insufficient_credits`	The account cannot run this request.
`429`	`rate_limited`	The key was rate-limited or its configured usage was exceeded.
`503`	`provider_unavailable`	The selected model’s provider is not available or not configured.
`502`	`generation_failed`	The provider call failed after the request was accepted.
`500`	`generation_failed`	An unexpected server failure during generation.
`500`	`server_error`	`GET /api/models` could not load the catalog.

Record the HTTP status and requestId when asking for help. Do not send the API key, prompt, raw request body, or raw image in support mail.

Create a key: Dashboard → API Keys
Model guides: How to choose a model

Artgen API Reference

Authentication

GET /api/models

GET /api/styles

POST /api/create

POST /api/convert

Success response

Errors

Next

On this page

Artgen API Reference

Authentication

GET /api/models

GET /api/styles

POST /api/create

POST /api/convert

Success response

Errors

Next

On this page

Artgen API Reference

AuthenticationCopy Anchor Link

GET /api/modelsCopy Anchor Link

GET /api/stylesCopy Anchor Link

POST /api/createCopy Anchor Link

POST /api/convertCopy Anchor Link

Success responseCopy Anchor Link

ErrorsCopy Anchor Link

NextCopy Anchor Link

On this page

Artgen API Reference

AuthenticationCopy Anchor Link

GET /api/modelsCopy Anchor Link

GET /api/stylesCopy Anchor Link

POST /api/createCopy Anchor Link

POST /api/convertCopy Anchor Link

Success responseCopy Anchor Link

ErrorsCopy Anchor Link

NextCopy Anchor Link

On this page

Authentication

GET /api/models

GET /api/styles

POST /api/create

POST /api/convert

Success response

Errors

Next

Authentication

GET /api/models

GET /api/styles

POST /api/create

POST /api/convert

Success response

Errors

Next