AI-powered generative image creation and editing.
{
"openapi": "3.1.0",
"info": {
"version": "3.0.0",
"title": "Firefly API",
"description": "REST API for Adobe Firefly services including image generation, image alteration, image upscaling, video generation, and other related services."
},
"servers": [
{
"url": "https://firefly-api.adobe.io",
"description": "Production server."
}
],
"security": [
{
"X-Api-Key": [],
"AccessToken": []
}
],
"tags": [
{
"name": "Common Operations",
"description": "Core Firefly API operations for generating and manipulating images and videos."
},
{
"name": "Composite Operations",
"description": "Object composite image generation: prompt-based composite, precise composite, and adaptive composite endpoints."
},
{
"name": "Upscale",
"description": "Image upscaling with the precise upsampler."
},
{
"name": "Manage jobs",
"description": "Endpoints for managing running asynchronous jobs."
}
],
"paths": {
"/v3/images/generate-async": {
"post": {
"operationId": "generateImagesV3Async",
"summary": "Generate images",
"description": "Generate images based on a text prompt. You may also include a reference image and Firefly will try to mimic the characteristics, such as color scheme, lighting, layout of objects in the image, etc.",
"tags": ["Common Operations"],
"parameters": [
{
"name": "x-model-version",
"in": "header",
"description": "Specify the Firefly model version to use for the image generation. When a custom model is used, a `customModelId` must also be passed in the request body.",
"required": false,
"schema": {
"type": "string",
"default": "image3",
"enum": [
"image3",
"image3_custom",
"image4_standard",
"image4_ultra",
"image4_custom"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateImagesRequestV3"
}
},
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_generateImagesV3Async"
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncAcceptResponseV3"
}
}
},
"description": "Accepted",
"headers": {
"Link": {
"description": "Links to check the job status or cancel the job.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"examples": {
"bad_request": {
"value": {
"error_code": "bad_request"
}
},
"empty_input_body": {
"value": {
"error_code": "empty_input_body"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"examples": {
"access_error": {
"value": {
"error_code": "access_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Forbidden",
"headers": {
"x-access-error": {
"description": "Indicates the reason access is not authorized.",
"schema": {
"type": "string",
"enum": [
"quota_exhausted",
"user_non_entitled",
"user_profile_denied",
"invalid_ims_scope"
]
}
}
}
},
"408": {
"content": {
"application/json": {
"examples": {
"timeout_error": {
"value": {
"error_code": "timeout_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Request Timeout"
},
"413": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Request Entity Too Large"
},
"415": {
"content": {
"application/json": {
"examples": {
"invalid_content_type": {
"value": {
"error_code": "invalid_content_type"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Unsupported Media Type"
},
"422": {
"content": {
"application/json": {
"examples": {
"validation_error": {
"value": {
"error_code": "validation_error",
"validation_errors": [
{
"ctx": {
"enum_values": [
"photo",
"art"
]
},
"loc": [
"body",
"contentClass"
],
"msg": "value is not a valid enumeration member; permitted: 'photo', 'art'",
"type": "type_error.enum"
}
]
}
},
"unsupported_value": {
"summary": "Unsupported value",
"value": {
"error_code": "validation_error",
"validation_errors": [
{
"loc": ["body", "seeds"],
"msg": "ensure this value has at most 1 items",
"type": "value_error.list.max_items"
}
]
}
},
"assertion_violation": {
"summary": "Assertion violation",
"value": {
"error_code": "cai_assertion_violation_error",
"message": "Request failed content assertion checks."
}
}
},
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/json": {
"examples": {
"rate_limited": {
"value": {
"error_code": "rate_limited"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Too Many Requests",
"headers": {
"retry-after": {
"description": "Indicates the date after which the client should retry the request.",
"schema": {
"type": "string"
}
},
"x-access-rate-limit-level": {
"description": "Indicates the level at which the rate limit was applied. Possible values are:\n- org: The rate limit was applied to the organization\n- account: The rate limit was applied to the organization's tech account.",
"schema": {
"type": "string"
}
}
}
},
"500": {
"content": {
"application/json": {
"examples": {
"runtime_error": {
"value": {
"error_code": "runtime_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Internal Server Error"
}
}
}
},
"/v4/images/generate-async": {
"post": {
"operationId": "firefly_image_v5_generate_async_v4",
"summary": "Generate images with Image5",
"description": "Generate images asynchronously using Firefly's Image5 model. When <code>referenceBlobs</code> is included in the request, omit <code>aspectRatio</code> or set it to <code>auto</code>.",
"tags": ["Common Operations"],
"parameters": [
{
"name": "x-model-version",
"in": "header",
"required": true,
"schema": {
"type": "string",
"enum": ["image5"],
"default": "image5"
},
"description": "The model version to use for image generation."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageGenerateRequestV3"
},
"examples": {
"fullPayload": {
"summary": "Full payload example",
"value": {
"prompt": "A futuristic city glowing at night, with neon lights and flying cars",
"aspectRatio": "auto",
"resolutionLevel": "2.4MP",
"modelId": "firefly_image",
"numVariations": 1,
"seeds": [42345],
"modelSpecificPayload": {
"localeCode": "en-US",
"prompt_reasoner": "quality"
},
"referenceBlobs": [
{
"source": {
"url": "https://example.com/reference-image.jpg"
},
"usage": "general"
}
]
}
},
"textToImageGeneration": {
"summary": "Text-to-Image generation",
"value": {
"prompt": "A hyper-detailed illustration of a floating city at sunrise",
"aspectRatio": "16:9",
"resolutionLevel": "4MP",
"modelId": "firefly_image",
"numVariations": 1,
"referenceBlobs": []
}
},
"imageToImageInstructEdit": {
"summary": "Image-to-Image instruct edit",
"value": {
"prompt": "Add warm sunset lighting and enhance the reflection on the water",
"resolutionLevel": "2.4MP",
"modelId": "firefly_image",
"numVariations": 1,
"referenceBlobs": [
{
"source": {
"uploadId": "123e4567-e89b-12d3-a456-426614174000"
},
"usage": "general"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncTaskResponse"
},
"example": {
"links": {
"cancel": {
"href": "https://firefly-api.adobe.io/v3/cancel/job-abc123"
},
"result": {
"href": "https://firefly-api.adobe.io/v3/status/job-abc123"
}
},
"progress": 0
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"404": {
"description": "Requested Resource Was Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"408": {
"description": "Request Timeout",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"410": {
"description": "Gone",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"415": {
"description": "Unsupported Media Type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
},
"examples": {
"invalid_enum": {
"summary": "Invalid enum value",
"value": {
"error_code": "validation_error",
"validation_errors": [
{
"loc": ["body", "aspectRatio"],
"msg": "value is not a valid enumeration member; permitted: '1:1', '4:3', '3:4', '16:9', '9:16', 'auto'",
"type": "type_error.enum"
}
]
}
},
"unsupported_value": {
"summary": "Unsupported value",
"value": {
"error_code": "validation_error",
"validation_errors": [
{
"loc": ["body", "numVariations"],
"msg": "ensure this value is less than or equal to 1",
"type": "value_error.number.not_le"
}
]
}
},
"assertion_violation": {
"summary": "Assertion violation",
"value": {
"error_code": "cai_assertion_violation_error",
"message": "Request failed content assertion checks."
}
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"451": {
"description": "Unavailable For Legal Reasons",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContentPolicyErrorResponse"
},
"examples": {
"prompt_unsafe": {
"summary": "Unsafe prompt",
"value": {
"error_code": "prompt_unsafe",
"message": "The prompt did not pass content policy checks."
}
},
"input_image_unsafe": {
"summary": "Unsafe input image",
"value": {
"error_code": "input_media_unsafe",
"message": "The input image did not pass content policy checks."
}
}
}
}
}
},
"499": {
"description": "Client Closed Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"501": {
"description": "Not Implemented",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
},
"503": {
"description": "Service Unavailable",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
}
}
}
}
},
"/v3/images/generate-similar-async": {
"post": {
"operationId": "generateSimilarImagesV3Async",
"summary": "Generate similar images",
"description": "Generate similar images based on a reference image that you provide as a parameter.",
"tags": ["Common Operations"],
"parameters": [
{
"name": "x-model-version",
"in": "header",
"description": "Specify the Firefly model version to use for the image generation.",
"required": false,
"schema": {
"type": "string",
"default": "image3",
"enum": [
"image3",
"image4_standard",
"image4_ultra"
]
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenerateSimilarImagesRequestV3"
}
},
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_generateSimilarImagesV3Async"
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncAcceptResponseV3"
}
}
},
"description": "Accepted",
"headers": {
"Link": {
"description": "Links to check the job status or cancel the job.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"examples": {
"bad_request": {
"value": {
"error_code": "bad_request"
}
},
"empty_input_body": {
"value": {
"error_code": "empty_input_body"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"examples": {
"access_error": {
"value": {
"error_code": "access_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Forbidden",
"headers": {
"x-access-error": {
"description": "Indicates the reason access is not authorized.",
"schema": {
"type": "string",
"enum": [
"quota_exhausted",
"user_non_entitled",
"user_profile_denied",
"invalid_ims_scope"
]
}
}
}
},
"408": {
"content": {
"application/json": {
"examples": {
"timeout_error": {
"value": {
"error_code": "timeout_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Request Timeout"
},
"413": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Request Entity Too Large"
},
"415": {
"content": {
"application/json": {
"examples": {
"invalid_content_type": {
"value": {
"error_code": "invalid_content_type"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Unsupported Media Type"
},
"422": {
"content": {
"application/json": {
"examples": {
"validation_error": {
"value": {
"error_code": "validation_error",
"validation_errors": [
{
"ctx": {
"enum_values": [
"photo",
"art"
]
},
"loc": [
"body",
"contentClass"
],
"msg": "value is not a valid enumeration member; permitted: 'photo', 'art'",
"type": "type_error.enum"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/json": {
"examples": {
"rate_limited": {
"value": {
"error_code": "rate_limited"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Too Many Requests",
"headers": {
"retry-after": {
"description": "Indicates the date after which the client should retry the request.",
"schema": {
"type": "string"
}
},
"x-access-rate-limit-level": {
"description": "Indicates the level at which the rate limit was applied. Possible values are:\n- org: The rate limit was applied to the organization\n- account: The rate limit was applied to the organization's tech account.",
"schema": {
"type": "string"
}
}
}
},
"500": {
"content": {
"application/json": {
"examples": {
"runtime_error": {
"value": {
"error_code": "runtime_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Internal Server Error"
}
}
}
},
"/v3/images/expand-async": {
"post": {
"operationId": "expandImagesV3Async",
"summary": "Expand image",
"description": "Change the aspect ratio or size of an image to expand it. Optionally, provide a text prompt to generate additional imagery for the expansion.",
"tags": ["Common Operations"],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExpandImageRequestV3"
}
},
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_expandImagesV3Async"
}
}
},
"required": true
},
"responses": {
"202": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncAcceptResponseV3"
}
}
},
"description": "Accepted",
"headers": {
"Link": {
"description": "Links to check the job status or cancel the job.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"examples": {
"bad_request": {
"value": {
"error_code": "bad_request"
}
},
"empty_input_body": {
"value": {
"error_code": "empty_input_body"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"examples": {
"access_error": {
"value": {
"error_code": "access_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Forbidden",
"headers": {
"x-access-error": {
"description": "Indicates the reason access is not authorized.",
"schema": {
"type": "string",
"enum": [
"quota_exhausted",
"user_non_entitled",
"user_profile_denied",
"invalid_ims_scope"
]
}
}
}
},
"408": {
"content": {
"application/json": {
"examples": {
"timeout_error": {
"value": {
"error_code": "timeout_error"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Request Timeout"
},
"413": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Request Entity Too Large"
},
"415": {
"content": {
"application/json": {
"examples": {
"invalid_content_type": {
"value": {
"error_code": "invalid_content_type"
}
}
},
"schema": {
"$ref": "#/components/schemas/ApiError"
}
}
},
"description": "Unsupported Media Type"
},
"422": {
"content": {
"application/json": {
"examples": {
"validation_error": {
"value": {
"error_code": "validation_error",
"validation_errors": [
{
"ctx": {
"enum_values": [
"photo",
"art"
]
},
"loc": [
"body",
"contentClass"
],
"msg": "value is not a valid enumeration member; permitted: 'photo', 'art'",
"type": "type_error.enum"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/ValidationErrorResponse"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/json": {
"examples": {
"rate_limited": {
"value": {
"error_code": "rate_limited"
}
}
},
"
# --- truncated at 32 KB (160 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-firefly-openapi.json