> ## Documentation Index > Fetch the complete documentation index at: https://docs.dreamlayer.io/llms.txt > Use this file to discover all available pages before exploring further. # Start or replay an execution > For images and sprites, credit and quota admission failures appear later in execution state; retryable admission failures remain queued. Video instead accepts a ready quote using only quote_id and max_credits and returns 202 JSON, or synchronous errors such as 402 insufficient_credits and 429 too_many_active_jobs. Use a stable Idempotency-Key and save the acceptance body before submitting. Video does not return an initial SSE stream. See https://docs.dreamlayer.io/agent-api/text-to-video. ## OpenAPI ````yaml /openapi/managed.yaml post /v1/execute openapi: 3.1.0 info: title: DreamLayer Agent API version: '1' description: >- Generate images, sprite sheets, and quoted videos; follow executions and retrieve owned outputs. Start with https://docs.dreamlayer.io/agent-api for authentication, limits, runnable examples, event recovery, and billing. Sprite sheets require account capability support and an approved credit ceiling. Video requires a quote before acceptance. Video schemas document the customer integration fields; response objects may contain additional fields. See https://docs.dreamlayer.io/agent-api/video. servers: - url: https://api.dreamlayer.io security: - bearerAuth: [] paths: /v1/execute: post: summary: Start or replay an execution description: >- For images and sprites, credit and quota admission failures appear later in execution state; retryable admission failures remain queued. Video instead accepts a ready quote using only quote_id and max_credits and returns 202 JSON, or synchronous errors such as 402 insufficient_credits and 429 too_many_active_jobs. Use a stable Idempotency-Key and save the acceptance body before submitting. Video does not return an initial SSE stream. See https://docs.dreamlayer.io/agent-api/text-to-video. operationId: execute parameters: - $ref: '#/components/parameters/Version' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/ExecuteRequest' - $ref: '#/components/schemas/VideoAccept' responses: '200': description: Sanitized server-sent events content: text/event-stream: schema: type: string '202': description: Durable execution accepted content: application/json: schema: oneOf: - $ref: '#/components/schemas/ExecutionAccepted' - $ref: '#/components/schemas/VideoExecution' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/VideoFailure' '403': $ref: '#/components/responses/VideoOrSharedFailure' '409': $ref: '#/components/responses/VideoOrSharedFailure' '422': $ref: '#/components/responses/InvalidRequest' '429': $ref: '#/components/responses/VideoOrSharedFailure' '500': $ref: '#/components/responses/TemporaryFailure' '503': $ref: '#/components/responses/VideoOrSharedFailure' components: parameters: Version: name: DreamLayer-Version in: header required: true schema: type: string const: '1' IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 200 schemas: ExecuteRequest: type: object additionalProperties: false properties: prompt: type: string minLength: 1 maxLength: 4000 respond: type: string minLength: 1 maxLength: 4000 conversation_id: type: string format: uuid input_asset_id: type: string format: uuid aspect_ratio: type: string default: '1:1' max_credits: type: number minimum: 0.1 maximum: 100 default: 1 options: $ref: '#/components/schemas/SpriteOptions' operation: type: string enum: - text_to_image - image_to_image - background_remove - upscale - sprite_sheet description: >- Optional. Name the operation to execute it deterministically: DreamLayer skips interpreting the prompt, so the request cannot be reclassified and cannot return a question event. No word in the prompt changes a named operation, and a named operation ignores an image remembered from an earlier turn in the same conversation. Omit it to let DreamLayer decide from the prompt. text_to_image must not carry input_asset_id; image_to_image, background_remove, upscale and sprite_sheet require it. sprite_sheet requires exactly one of options.action or options.animation_prompt. Read the authenticated /v1/sprite-pricing estimate for the requested frame_count and background, then set an explicitly authorized max_credits ceiling. Current amounts can have four decimal places. Estimates are non-binding; admission refuses a price above the ceiling before debiting. Default capabilities pricing is historical compatibility data, not a current account estimate. Put custom animation instructions in options.animation_prompt, not prompt. Sprite requests have no customer cancellation. Other operations require max_credits of 1 and do not accept options. upscale doubles each side, so the input's longest side must be 2048 or smaller: 4096 is the delivery ceiling and an oversize request is refused at execution admission before paid processing starts. That also means an upscaled image is AT maximum_input_dimension and cannot be upscaled again. oneOf: - required: - operation - input_asset_id - options properties: operation: const: sprite_sheet not: required: - respond - required: - prompt not: anyOf: - required: - respond - required: - operation properties: operation: const: sprite_sheet - required: - respond - conversation_id not: required: - prompt VideoAccept: type: object additionalProperties: false required: - quote_id - max_credits properties: quote_id: type: string format: uuid max_credits: description: >- Positive API credit ceiling, at most 100, covering the quoted amount. Decimal strings preserve exact amounts. Never increase without approval. oneOf: - type: number exclusiveMinimum: 0 maximum: 100 - type: string pattern: >- ^(?:0\.(?=[0-9]*[1-9])[0-9]+|[1-9][0-9]?(?:\.[0-9]+)?|100(?:\.0+)?)$ examples: - quote_id: d34db33f-0000-4000-8000-000000000002 max_credits: '33' ExecutionAccepted: type: object additionalProperties: false required: - execution_id - conversation_id - status properties: execution_id: type: string format: uuid conversation_id: type: string format: uuid status: type: string enum: - needs_input - queued - running - completed - failed - cancelled VideoExecution: type: object additionalProperties: false required: - execution_id - conversation_id - status - image_job - video_job properties: execution_id: type: string format: uuid conversation_id: type: string format: uuid status: $ref: '#/components/schemas/VideoState' image_job: type: 'null' video_job: type: object additionalProperties: true description: >- Documented integration fields. Additional response fields can include original request data; do not log full responses. required: - stage - requested_settings - metadata - credits - credits_restored - settled_credits - reserved_credits - billing_note - error_code - retention_expires_at - download_url properties: stage: $ref: '#/components/schemas/VideoState' requested_settings: $ref: '#/components/schemas/VideoSettings' metadata: type: - object - 'null' description: >- Actual delivered metadata, available after validation. Dimensions and duration can differ slightly from nominal settings. properties: width: type: integer height: type: integer duration_seconds: type: number fps: type: number audio_streams: type: integer codec: type: string content_type: type: string const: video/mp4 bytes: type: integer maximum: 268435456 sha256: type: string credits: type: string credits_restored: type: boolean settled_credits: type: string reserved_credits: type: string billing_note: type: string error_code: type: - string - 'null' retention_expires_at: type: - string - 'null' format: date-time download_url: type: - string - 'null' description: >- Owned relative asset path on completion; authenticate only at the API origin. created_at: type: - string - 'null' format: date-time completed_at: type: - string - 'null' format: date-time SpriteOptions: type: object additionalProperties: false description: >- Supply exactly one non-null action or animation_prompt. Presets default to loop playback; custom instructions default to once. Frame size affects the square export canvas, not price or guaranteed source detail. Insufficient distinct frames fail explicitly; frames are not duplicated or interpolated to meet the count. oneOf: - required: - action properties: action: type: string enum: - walk - run - idle animation_prompt: type: 'null' - required: - animation_prompt properties: animation_prompt: type: string minLength: 1 maxLength: 4000 pattern: \S action: type: 'null' properties: action: type: - string - 'null' enum: - walk - run - idle - null description: >- Preset alternative to animation_prompt. Walk and run use a right-facing side view; idle keeps the reference viewpoint. animation_prompt: type: - string - 'null' minLength: 1 maxLength: 4000 pattern: \S description: >- Describe the subject's animation, viewpoint, movement and style. Characters, creatures, objects, effects and turntables can be requested; quality is not guaranteed. animation_mode: type: - string - 'null' enum: - loop - once - null description: >- Defaults to loop for presets and once for custom instructions. Once preserves the beginning and ending; a loop is not guaranteed seamless. Use atlas frame_durations_ms for playback timing. frame_count: type: integer minimum: 7 maximum: 100 default: 12 frame_size: type: integer enum: - 32 - 64 - 128 - 256 - 512 - 720 - 1080 default: 512 description: >- Square PNG frame and sheet-cell size in pixels, with shared alignment and transparent padding. Does not change pricing. background: type: - string - 'null' enum: - remove - keep - null description: >- Omit or send remove for transparent frames. Send keep to skip background removal and take the frames as generated, priced at $0.32 plus $0.01 per frame converted to credits at the account's undiscounted purchase rate. examples: - action: walk frame_count: 12 - animation_prompt: >- Rotate this character through a full 360-degree turn with a fixed pose and stationary camera. animation_mode: loop frame_count: 7 frame_size: 512 - animation_prompt: Open the chest lid and hold it open. animation_mode: once frame_count: 7 frame_size: 256 VideoState: type: string enum: - queued - submitting - uncertain - generating - delivering - completed - failed - cancelled - expired VideoSettings: type: object additionalProperties: false required: - duration_seconds - resolution - aspect_ratio - generate_audio properties: duration_seconds: type: integer resolution: type: string const: 720p aspect_ratio: type: string description: >- Resolved text aspect or the source-driven profile marker for image video. Read delivered metadata for actual width and height. generate_audio: type: boolean ErrorEnvelope: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - reason - message - category - retryable - request_id properties: code: type: string description: Legacy uppercase code retained for existing clients. reason: $ref: '#/components/schemas/PublicErrorReason' message: type: string category: type: string retryable: type: boolean request_id: type: string format: uuid details: type: object description: >- Optional sanitized validation detail. Submitted values are never echoed. additionalProperties: true VideoErrorEnvelope: type: object required: - error properties: error: type: object required: - code - reason - message - retryable properties: code: type: string reason: type: string message: type: string retryable: type: boolean PublicErrorReason: type: string enum: - invalid_request - authentication_failed - access_denied - resource_not_found - insufficient_credits - conflict - too_many_active_jobs - rate_limited - quota_exceeded - content_refused - temporarily_unavailable - generation_failed - insufficient_frames - prompt_policy_blocked - feature_unavailable responses: InvalidRequest: description: Invalid request, including a missing required Authorization header headers: Cache-Control: schema: type: string const: no-store Pragma: schema: type: string const: no-cache X-Request-ID: schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Unauthenticated: description: >- Invalid or revoked API key. A missing Authorization header returns 422 invalid_request. headers: Cache-Control: schema: type: string const: no-store Pragma: schema: type: string const: no-cache X-Request-ID: schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' VideoFailure: description: >- Video request rejected. Inspect error.reason and retryable. Credit or capacity rejection on acceptance does not create an execution. content: application/json: schema: $ref: '#/components/schemas/VideoErrorEnvelope' VideoOrSharedFailure: description: >- Video business error or shared validation, authentication, or request-limit error. See the operation-specific recovery guide. content: application/json: schema: anyOf: - $ref: '#/components/schemas/VideoErrorEnvelope' - $ref: '#/components/schemas/ErrorEnvelope' TemporaryFailure: description: Retryable service failure headers: Cache-Control: schema: type: string const: no-store Pragma: schema: type: string const: no-cache X-Request-ID: schema: type: string format: uuid content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.