Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Generate image

On this page
POST/api/content/image

Generate an image from a text prompt. Pass image_urls to edit those images with the prompt instead of generating a new one. Returns the image URL.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/content/image' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "Edit the lighting while preserving this artist.",
  "image_urls": [
    "https://example.com/artist.png"
  ],
  "num_images": 1
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://api.recoupable.dev/api/content/image' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "Edit the lighting while preserving this artist.",
  "image_urls": [
    "https://example.com/artist.png"
  ],
  "num_images": 1
}'

Request body required

Image generation parameters

application/json

promptstring

Text prompt used to generate or edit the image

image_urlsarray<string>

Reference images to edit (1-10 HTTP(S) URLs). When provided, edits these images with prompt instead of generating a new one.

minItems: 1 · maxItems: 10

Item properties for image_urls

string

num_imagesinteger

Number of images to generate (1-4)

Default: 1

minimum: 1 · maximum: 4

aspect_ratiostring · enum

Output aspect ratio. If omitted, the model chooses automatically based on the request.

Values: "21:9", "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "9:21"

output_formatstring · enum

Format of the generated image

Values: "jpeg", "png", "webp"

Default: "webp"

sync_modeboolean

If true, the image is returned as a data URI and is not persisted in the request history

Default: false

reference_image_urlstring

Compatibility alias translated into image_urls. Combined unique reference list is limited to 10. New clients must use image_urls.

format: uri

imagesarray<string>

Compatibility alias translated into image_urls. Combined unique reference list is limited to 10. New clients must use image_urls.

Item properties for images

string

Responses

200Image generated successfully

application/json

imageUrlstringrequired

URL of the first generated image

format: uri

imagesarray<string>required

URLs of all generated images. Contains one element when num_images is 1.

Item properties for images

string

400Validation failed — invalid or missing request body fields

application/json

errorstringrequired

Error message describing what went wrong

Example: "Unauthorized"

401Unauthorized — invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong

Example: "Unauthorized"

402Insufficient credits. Charged per generated image at the pinned model's rate ($0.01 per image). A free-tier account without sufficient credits receives a 402.

application/json

errorstringrequired

Error message describing what went wrong

Example: "Unauthorized"

500Internal server error

application/json

errorstringrequired

Error message describing what went wrong

Example: "Unauthorized"

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json
View operation source
json
{
  "operationId": "postContentImage",
  "description": "Generate an image from a text prompt. Pass `image_urls` to edit those images with the prompt instead of generating a new one. Returns the image URL.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Image generation parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ContentCreateImageRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Image generated successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentCreateImageResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation failed — invalid or missing request body fields",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits. Charged per generated image at the pinned model's rate ($0.01 per image). A free-tier account without sufficient credits receives a 402.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ContentErrorResponse"
          }
        }
      }
    }
  }
}