> For the complete documentation index, see [llms.txt](https://docs.claid.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claid.ai/image-generation-api/api-reference.md). # API Reference ### Image generation contract Below you can see all possible options for the request body. See the Image Generation Options and Image Generation I/O sections to learn more about image operations. ```json { "input": "A delicious ceviche cheesecake slice", "options": { "number_of_images": 1, "guidance_scale": 5.0 }, "output": "storage://{storage_name}/{image_folder}/" } ``` ## Image Generate > Specifies: \ > \- text prompt for image generation (\`input\`)\ > \- image generation options (\`options\`)\ > \- where results will be stored (\`output\`) ```json {"openapi":"3.1.0","info":{"title":"Claid REST API","version":"v1"},"tags":[{"name":"Image","description":"Encompasses operations with images."}],"security":[{"OAuth2PasswordBearer":[]},{"OAuth2PasswordBearer":["image_editing"]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"token"}},"description":"To work with the Claid API, send requests over HTTPS and authenticate using the `Authorization` header in the following format:`Authorization: Bearer `. You do not need to provide a password.\n\nTo get your API key, [sign in to your Claid account](https://claid.ai/login) and click ***Create API key*** button from the ***Overview*** or ***API keys*** pages.\n\nClaid API’s base URL is `https://api.claid.ai/v1/`. All available endpoints are listed in the [Storage](#tag/Storage) and [Image](#tag/Image) sections. \n\n## Bearer\n\nThis API uses OAuth 2.0 [bearer token](https://datatracker.ietf.org/doc/html/rfc6750) (API key) to authorize requests."}},"schemas":{"GenerateRequest":{"title":"GenerateRequest","required":["input"],"type":"object","properties":{"input":{"title":"Text prompt for image generation","maxLength":1024,"minLength":3,"type":"string","description":"Text prompt that will be used to generate image(s). Should be from 3 to 1024 characters. "},"options":{"title":"Image generate options","allOf":[{"$ref":"#/components/schemas/ImageGenerateOptions"}],"description":"Customize the image generation process so that the output images meet your requirements.","default":{"number_of_images":4,"guidance_scale":5}},"output":{"title":"Output folder URL","maxLength":4096,"minLength":1,"type":"string","description":"URL of the output folder. If `output` is not defined, we store the output image on our bucket and return the temporary URL, in this case images are stored for one day.","format":"uri"}},"additionalProperties":false},"ImageGenerateOptions":{"title":"ImageGenerateOptions","type":"object","properties":{"number_of_images":{"title":"Number of images","maximum":4,"minimum":1,"type":"integer","description":"Number of images to generate. By default 4 images will be generated.","default":4},"guidance_scale":{"title":"Guidance scale","exclusiveMaximum":50,"minimum":1,"type":"number","description":"Guidance scale is used to make the generation better match the prompt potentially at the cost of image quality or diversity. Values between 5 and 7 are usually good choices, but sometimes more control is achieved with values such as 12. By default the pipeline uses a guidance scale of 5.","default":5}},"additionalProperties":false},"Response_GenerateResponse_":{"title":"Response[GenerateResponse]","type":"object","properties":{"data":{"$ref":"#/components/schemas/GenerateResponse"}},"description":"Wrapper for responses"},"GenerateResponse":{"title":"GenerateResponse","required":["input","output"],"type":"object","properties":{"input":{"$ref":"#/components/schemas/GeneratePipelineInputObject"},"output":{"title":"Output","type":"array","items":{"$ref":"#/components/schemas/PipelineOutputObject"}},"profiling":{"title":"Profiling","type":"object"}}},"GeneratePipelineInputObject":{"title":"GeneratePipelineInputObject","required":["text"],"type":"object","properties":{"text":{"title":"Text","type":"string","description":"Text prompt for image generation"}}},"PipelineOutputObject":{"title":"PipelineOutputObject","required":["ext","mps","mime","format","width","height"],"type":"object","properties":{"ext":{"title":"Ext","type":"string","description":"File extension. Can have values: `\"jpg\"`, `\"png\"`, `\"avif\"`"},"mps":{"title":"Mps","type":"number","description":"Megapixel count"},"mime":{"title":"Mime","type":"string","description":"MIME type (also known as ‘media type’)"},"format":{"title":"Format","type":"string","description":"File format. Can have values: `\"jpeg\"`, `\"png\"`, `\"avif\"`"},"width":{"title":"Width","type":"integer","description":"Image width in pixels"},"height":{"title":"Height","type":"integer","description":"Image height in pixels"},"tmp_url":{"title":"Tmp Url","type":"string","description":"Temporal URL of a processed image"},"object_key":{"title":"Object Key","type":"string","description":"Path to a processed image in a bucket"},"object_bucket":{"title":"Object Bucket","type":"string","description":"Bucket name"},"object_uri":{"title":"Object Uri","type":"string","description":"URI of a processed image in a bucket"},"claid_storage_uri":{"title":"Claid Storage Uri","type":"string","description":"URI of a processed image in a storage"}}},"HttpErrorDetails":{"title":"HttpErrorDetails","required":["error_code","error_type","error_message"],"type":"object","properties":{"error_code":{"title":"Error Code","type":"string"},"error_type":{"$ref":"#/components/schemas/ErrorType"},"error_message":{"title":"Error Message","type":"string"},"error_details":{"title":"Error Details","type":"object","default":{}}}},"ErrorType":{"title":"ErrorType","enum":["auth","dlvr","general","le","survey","storage","image","user_settings","user","validation","analytics","scene","billing","web","runtime_settings","animation","custom_models"],"type":"string","description":"An enumeration."}}},"paths":{"/v1/image/generate":{"post":{"tags":["Image"],"summary":"Image Generate","description":"Specifies: \n- text prompt for image generation (`input`)\n- image generation options (`options`)\n- where results will be stored (`output`)","operationId":"image_generate_v1_image_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response_GenerateResponse_"}}}},"401":{"description":"Authorization is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"402":{"description":"No API calls left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"403":{"description":"Not enough permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"422":{"description":"Unprocessable Entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}},"429":{"description":"Too many requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpErrorDetails"}}}}}}}}} ``` **Request** {% tabs %} {% tab title="HTTP" %} 
POST /v1/image/generate HTTP/1.1
Host: api.claid.ai
Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

{
    "input": "A delicious ceviche cheesecake slice",
    "options": {
        "number_of_images": 2,
        "guidance_scale": 5
    }
}
{% endtab %} {% tab title="cURL" %} ```shell curl -X POST --location "https://api.claid.ai/v1/image/generate" --http1.1 \ -H "Host: api.claid.ai" \ -H "Authorization: Bearer {YOUR_API_KEY}" \ -H "Content-Type: application/json" \ -d "{ \"input\": \"A delicious ceviche cheesecake slice\", \"options\": { \"number_of_images\": 2, \"guidance_scale\": 5 } }" ``` {% endtab %} {% endtabs %} #### Request headers: In order to send a request, you should set `Content-Type` header to let our system know that you provide a valid JSON payload and `Authorization` header with a generated API key to identify yourself as a Claid user. ```http Content-Type: application/json Authorization: Bearer {YOUR_API_KEY} ``` #### **Read a response** Once you have made the request to `https://api.claid.ai/v1/image/generate` you will get a response with information about input text and output images. Image information is shown in the response: | Parameter | Type | Description | | --------- | ------- | -------------------------------------------------------------------------- | | ext | string | File extension. Will have `png` value | | mps | integer | Megapixel count | | mime | string | MIME type (also known as ‘media type’) | | width | integer | Image width in pixels | | height | integer | Image height in pixels | | format | string | File format. Will have `png` value | | tmp\_url | string | Temporary URL of a processed image. Will be empty if `output` is specified | **Response body** ```json { "data": { "input": { "text": "A delicious ceviche cheesecake slice" } }, "output": [ { "ext": "png", "mps": 1.048576, "mime": "image/png", "format": "PNG", "width": 1024, "height": 1024, "tmp_url": "https://storage.googleapis.com/production-leapi-tmp-public/733a7c8f-1fea-4097-8fd4-17f54c94d998/eyXNp9_1.png" }, { "ext": "png", "mps": 1.048576, "mime": "image/png", "format": "PNG", "width": 1024, "height": 1024, "tmp_url": "https://storage.googleapis.com/production-leapi-tmp-public/733a7c8f-1fea-4097-8fd4-17f54c94d998/eyXNp9_2.png" }, ] } } ``` #### Response headers: [Rate limit](/rate-limits.md) headers will help you understand what number of requests you are able to send according to the current limits on your account: ```http ratelimit-limit: 120, 120;w=60, 4;w=1 ratelimit-remaining: 119 ratelimit-reset: 34 ``` Request ID header allows to identify your request during image processing, so we are able to help you with troubleshooting and profiling your request if needed. ```http x-request-id: 9b321763-1d09-4072-932b-ff031475affa ```