Developers

Appearance

Generate an image from a prompt ​

Generate one image from a text prompt, optionally guided by reference images (up to the model's limit, 3 to 16), with no design involved.

POST/images/text-to-imageAPI Reference

Sample request ​

bash
curl -X POST \
  -H "x-api-key: {YOUR-API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox sitting in fresh snow at sunrise, soft light",
    "model": "nano-banana-2",
    "aspect_ratio": "16:9",
    "callback_url": "https://webhook.mycompany.com/abyssale"
  }' \
  https://api.abyssale.com/images/text-to-image
javascript
// No SDK method yet — plain fetch (Node 18+). Set ABYSSALE_API_KEY before running.
const res = await fetch('https://api.abyssale.com/images/text-to-image', {
  method: 'POST',
  headers: { 'x-api-key': process.env.ABYSSALE_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'The same bottle on a marble kitchen counter, morning light',
    model: 'nano-banana-2',
    aspect_ratio: '16:9',
    reference_image_urls: ['https://example.com/product.png'],
  }),
});

const body = await res.json();
if (res.status !== 202) console.error(res.status, body.id, body.message);
else console.log(body.job_id);
python
# No SDK method yet — plain requests. Set ABYSSALE_API_KEY before running.
import os
import requests

r = requests.post(
    "https://api.abyssale.com/images/text-to-image",
    headers={"x-api-key": os.environ["ABYSSALE_API_KEY"]},
    json={
        "prompt": "The same bottle on a marble kitchen counter, morning light",
        "model": "nano-banana-2",
        "aspect_ratio": "16:9",
        "reference_image_urls": ["https://example.com/product.png"],
    },
    timeout=30,
)
r.raise_for_status()
print(r.json()["job_id"])

Inputs ​

FieldTypeRequiredDescription
promptstringYesWhat to generate. At least 3 words, at most 4 000 characters.
modelstringNoModel id, from GET /ai-models?operation=images_text_to_image. Omitted: the workspace's default.
aspect_ratiostringNoThe image's shape, as the model names it. Omitted: the model's default. See below.
qualitystringNoQuality or resolution tier, as the model names it. Omitted: the model's default. See below.
reference_image_urlsarrayNoPublic http(s) image URLs that guide the generation, up to the model's limit (3 to 16). See below.
callback_urlstring (uri)Nohttp(s) URL that receives the ASSET_JOB_FINALIZED webhook when the job ends.

aspect_ratio and quality ​

Each model accepts its own values — a ratio such as 16:9 for some, a size such as landscape_16_9 or 1536x1024 for others — and some take no quality at all. GET /ai-models?operation=images_text_to_image lists, per model, the accepted values (aspect_ratios.allowed, qualities.allowed) and the default. Send quality only to a model that lists qualities.

A value the model does not accept answers 400 unknown_enum_value before anything is queued or charged, with the accepted values in errors[].expected.

reference_image_urls ​

A product to stage, a style to follow. The images are downloaded when the job runs, and one that cannot be read fails the job with invalid_input_asset. Each one is a PNG, JPEG or WebP, up to 20 MB.

RuleOtherwise
The model must accept reference images.400 unknown_enum_value on model, listing the models that do.
At most the model's max_reference_images, from GET /ai-models: 3 to 16 depending on the model.400 out_of_range on reference_image_urls, before anything is queued or charged.

Some models charge more per reference image.

Response ​

202, before anything is processed:

json
{ "job_id": "3b7d91c2-4869-11f0-96f2-0a00d9eb8f78", "status": "PENDING" }

Follow the job by polling or webhook.

Output ​

One image per job: a completed job has exactly one entry in outputs. Its mime_type is the format the model produced, e.g. image/png or image/jpeg.

json
{
  "job_id": "3b7d91c2-4869-11f0-96f2-0a00d9eb8f78",
  "operation": "images_text_to_image",
  "status": "COMPLETED",
  "outputs": [
    { "type": "image", "url": "https://production-banners.s3.eu-west-1.amazonaws.com/text_to_image/d3b07384-d113-4ec6-a3b5-2f7c6e1a9b10/a7c4e2d9-1f3b-4e8a-9c6d-5b2e8f0a1d34.png", "mime_type": "image/png" }
  ],
  "credits": { "generation_credits": 0, "ai_credits": 7 },
  "error": null,
  "created_at": "2026-09-21T14:15:02Z",
  "finalized_at": "2026-09-21T14:15:19Z"
}

Every field is described under Poll the job.

Credits and errors ​

  • AI credits, by model, quality, aspect_ratio and reference images: 1 to 89 per image — see Credits → AI credits. Checked against the workspace's balance before queueing, charged only once the job completes.
  • The provider refusing the prompt ends the job FAILED with invalid_input.
  • A reference image that cannot be downloaded or read ends it with invalid_input_asset.

The other refusals and failures are shared by every action — see Errors.