> ## Documentation Index
> Fetch the complete documentation index at: https://edenai-docs-add-eng21-provider-data-policies.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Response

> Create a model response.



## OpenAPI

````yaml https://api.edenai.run/v3/docs/openapi.json post /v3/responses
openapi: 3.1.0
info:
  title: Eden AI API V3
  version: 3.0.0
servers:
  - url: https://api.edenai.run
    description: Production server
security: []
paths:
  /v3/responses:
    post:
      tags:
        - Responses
      summary: Create Response
      description: Create a model response.
      operationId: create_response_v3_responses_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LLMResponseObject'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - AuthBearer: []
components:
  schemas:
    ResponsesBody:
      properties:
        routing:
          anyOf:
            - $ref: '#/components/schemas/ProviderRoutingPreferences'
            - type: 'null'
          description: >-
            How to pick between the providers that serve the requested model.
            Applies only when `model` is a model name with no provider prefix
            (e.g. 'gpt-5.5'); ignored for a concrete 'provider/model' id, which
            already names its provider. This does not choose the model — for
            that see `router_candidates` with model='@edenai'.
        fallbacks:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 3
            - type: 'null'
          title: Fallbacks
          description: >-
            List of fallback model IDs to try if the primary model fails. Models
            are tried in order. Example: ['anthropic/claude-3-opus',
            'openai/gpt-4o']
        session_id:
          anyOf:
            - type: string
              maxLength: 256
            - type: 'null'
          title: Session Id
          description: >-
            Identifies a conversation, so its requests keep reaching the
            provider that holds its prompt cache. Any stable string you choose —
            a thread id, a ticket number, an agent run. Also accepted as the
            `x-session-id` header, for clients that cannot add body fields; the
            body field wins if both are sent. Without one, a conversation is
            recognised from its opening messages instead.
        router_candidates:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Router Candidates
          description: >-
            Models the '@edenai' router may choose BETWEEN — it picks the model,
            whereas `routing` picks the provider for a model you already named.
            Used only when model='@edenai'. Each entry should be
            'provider/model', e.g. ['openai/gpt-4o',
            'anthropic/claude-3-5-sonnet-20241022']. If not provided, defaults
            to all available models.
        model:
          type: string
          title: Model
          description: Model identifier, e.g. 'openai/gpt-4o'
        input:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/EasyInputMessage'
                  - $ref: '#/components/schemas/ResponseInputItem'
              type: array
            - type: 'null'
          title: Input
          description: >-
            Text, image, or file inputs to the model. Optional when continuing a
            conversation via previous_response_id.
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
          description: >-
            System/developer instructions prepended to input. Not carried over
            when using previous_response_id.
        previous_response_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Response Id
          description: >-
            ID of a prior response to continue a multi-turn conversation. The
            provider manages conversation state server-side.
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Stream
          description: Whether to stream the response via server-sent events.
          default: false
        tools:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tools
          description: >-
            List of tools the model may call (function, web_search, file_search,
            etc.).
        tool_choice:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Tool Choice
          description: >-
            Controls which tool is called. 'auto', 'required', 'none', or a
            specific tool object.
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
        top_p:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Top P
        max_output_tokens:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Output Tokens
        reasoning:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Reasoning
          description: 'Reasoning configuration, e.g. {''effort'': ''low''|''medium''|''high''}.'
        truncation:
          anyOf:
            - type: string
              enum:
                - auto
                - disabled
            - type: 'null'
          title: Truncation
          description: How to handle context that exceeds the model's context window.
        store:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Store
          description: >-
            Whether the provider should store the response server-side for later
            retrieval.
          default: true
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Up to 16 key-value pairs for tagging.
        user:
          anyOf:
            - type: string
            - type: 'null'
          title: User
          description: Stable end-user identifier for abuse detection.
        prompt_cache_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Cache Key
          description: >-
            Prompt-cache routing hint (OpenAI): requests sharing a key and a
            common prompt prefix are routed to the same cache shard, improving
            hit rates for high-volume shared prefixes. Forwarded to providers
            that support it, dropped elsewhere. Also read for provider
            stickiness when no `session_id` or `x-session-id` is given.
        prompt_cache_retention:
          anyOf:
            - type: string
              enum:
                - in_memory
                - 24h
            - type: string
            - type: 'null'
          title: Prompt Cache Retention
          description: >-
            How long the provider retains the prompt cache — OpenAI currently
            accepts "in_memory" (provider default, typically 5-10 minutes) and
            "24h" (extended retention, supported on gpt-5.x and gpt-4.1). The
            known values are advertised in the schema but not enforced: the
            value is passed through verbatim for the provider to validate, so
            new provider values work without an Eden AI release. Dropped for
            providers that don't support it.
        prompt_cache_options:
          anyOf:
            - $ref: '#/components/schemas/PromptCacheOptions'
            - type: 'null'
          description: >-
            Request-level prompt-cache settings (mode and ttl) for OpenAI
            GPT-5.6 and newer models. Ignored by models that don't support
            prompt caching.
        parallel_tool_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Parallel Tool Calls
        text:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Text
          description: >-
            Text output configuration, e.g. {'format': {'type': 'json_schema',
            ...}}.
        include:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Include
          description: Additional output data to include, e.g. 'file_search_call.results'.
        background:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Background
          description: Whether to run the model response in the background.
      type: object
      required:
        - model
      title: ResponsesBody
    LLMResponseObject:
      properties:
        cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Cost
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
        id:
          type: string
          title: Id
        object:
          type: string
          const: response
          title: Object
          default: response
        created_at:
          type: integer
          title: Created At
        model:
          type: string
          title: Model
        status:
          type: string
          title: Status
        output:
          items:
            anyOf:
              - $ref: '#/components/schemas/ResponseOutputMessage'
              - additionalProperties: true
                type: object
          type: array
          title: Output
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
        previous_response_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Response Id
        usage:
          anyOf:
            - $ref: '#/components/schemas/ResponseUsage'
            - type: 'null'
        error:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Error
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
      type: object
      required:
        - id
        - created_at
        - model
        - status
        - output
      title: LLMResponseObject
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProviderRoutingPreferences:
      properties:
        sort:
          anyOf:
            - type: string
              enum:
                - cost
                - speed
                - latency
                - exact
            - type: 'null'
          title: Sort
          description: >-
            What to optimise for when several providers serve the requested
            model. 'cost' (default) picks the cheapest for this request's shape;
            'speed' the highest tokens/second; 'latency' the fastest to first
            token; 'exact' the most reliable at producing well-formed tool calls
            / structured output. Health is always a filter first — no mode will
            route you to a failing provider. Can also be written as a model
            suffix, e.g. 'gpt-5.5:speed'.
        sticky:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Sticky
          description: >-
            Keep a conversation on the provider holding its prompt cache. On by
            default, and only ever active for models whose providers discount
            cache reads. Set false to route every request independently on price
            instead. Naming an explicit `sort` also takes priority over cache
            affinity.
        allow_fallbacks:
          type: boolean
          title: Allow Fallbacks
          description: >-
            Whether other providers of the same model may be tried when the
            chosen one fails. Set false to pin the request to the single best
            provider: it then fails rather than silently moving to another
            seller. useful when a cache-warm prompt would cold-miss elsewhere.
            This governs PROVIDERS of the requested model only; models you list
            in `fallbacks` are your own choice and are always kept.
          default: true
        allowed_providers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Providers
          description: >-
            Restrict routing to these providers, e.g. ['openai', 'anthropic'].
            Only providers that serve the requested model are considered, so an
            entry that does not sell it is simply inert. If none of them do, the
            request fails rather than falling back to a provider you excluded.
            Case-insensitive. Applies to routed providers only. a concrete
            'provider/model' you named in `fallbacks` is your own choice and is
            kept.
      type: object
      title: ProviderRoutingPreferences
      description: >-
        How to choose between SELLERS of one model — not which model to use.


        Only meaningful when `model` is a canonical name (`gpt-5.5`) rather than
        a concrete

        `provider/model` — with a concrete id there is nothing to choose
        between. For choosing the

        MODEL itself see ``router_candidates`` and ``model="@edenai"``, which is
        a different router.
    EasyInputMessage:
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - developer
          title: Role
        content:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/ResponseInputText'
                  - $ref: '#/components/schemas/ResponseInputImage'
                  - $ref: '#/components/schemas/ResponseInputFile'
                  - additionalProperties: true
                    type: object
              type: array
          title: Content
        type:
          type: string
          const: message
          title: Type
          default: message
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        cache_control:
          anyOf:
            - $ref: '#/components/schemas/CacheControl'
            - type: 'null'
          description: >-
            Optional prompt-cache marker. When set, this message becomes a cache
            boundary: prefix content is stored and reused on subsequent requests
            to reduce latency and cost. Silently ignored by providers that don't
            support prompt caching.
      additionalProperties: true
      type: object
      required:
        - role
        - content
      title: EasyInputMessage
    ResponseInputItem:
      properties:
        type:
          type: string
          title: Type
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
      additionalProperties: true
      type: object
      required:
        - type
      title: ResponseInputItem
      description: >-
        Non-message input item forwarded to the provider as-is (reasoning,
        function_call, etc.).
    PromptCacheOptions:
      properties:
        mode:
          anyOf:
            - type: string
              enum:
                - implicit
                - explicit
            - type: string
            - type: 'null'
          title: Mode
          description: >-
            "implicit" (default) caches automatically and also honors any
            prompt_cache_breakpoint you set; "explicit" caches only the blocks
            you mark with prompt_cache_breakpoint. Known values are advertised
            in the schema but not enforced.
        ttl:
          anyOf:
            - type: string
              const: 30m
            - type: string
            - type: 'null'
          title: Ttl
          description: >-
            How long to keep the prompt cache, e.g. "30m". Leave unset for the
            provider default. Known values are advertised in the schema but not
            enforced.
      additionalProperties: true
      type: object
      title: PromptCacheOptions
      description: >-
        Request-level prompt-cache settings (OpenAI GPT-5.6 and newer).


        Controls how this request's prompt cache behaves — whether caching
        happens

        automatically or only on the blocks you mark with
        ``prompt_cache_breakpoint``, and

        how long the cache is kept. Ignored by models that don't support prompt
        caching.
    ResponseOutputMessage:
      properties:
        id:
          type: string
          title: Id
        type:
          type: string
          const: message
          title: Type
        role:
          type: string
          const: assistant
          title: Role
        status:
          type: string
          title: Status
        content:
          items:
            anyOf:
              - $ref: '#/components/schemas/ResponseOutputText'
              - $ref: '#/components/schemas/ResponseOutputRefusal'
              - additionalProperties: true
                type: object
          type: array
          title: Content
      type: object
      required:
        - id
        - type
        - role
        - status
        - content
      title: ResponseOutputMessage
    ResponseUsage:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        total_tokens:
          type: integer
          title: Total Tokens
        input_tokens_details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Input Tokens Details
        output_tokens_details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Output Tokens Details
      type: object
      required:
        - input_tokens
        - output_tokens
        - total_tokens
      title: ResponseUsage
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ResponseInputText:
      properties:
        cache_control:
          anyOf:
            - $ref: '#/components/schemas/CacheControl'
            - type: 'null'
        prompt_cache_breakpoint:
          anyOf:
            - $ref: '#/components/schemas/PromptCacheBreakpoint'
            - type: 'null'
        type:
          type: string
          const: input_text
          title: Type
        text:
          type: string
          title: Text
      type: object
      required:
        - type
        - text
      title: ResponseInputText
    ResponseInputImage:
      properties:
        cache_control:
          anyOf:
            - $ref: '#/components/schemas/CacheControl'
            - type: 'null'
        prompt_cache_breakpoint:
          anyOf:
            - $ref: '#/components/schemas/PromptCacheBreakpoint'
            - type: 'null'
        type:
          type: string
          const: input_image
          title: Type
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        file_id:
          anyOf:
            - type: string
            - type: 'null'
          title: File Id
        detail:
          type: string
          enum:
            - low
            - high
            - auto
          title: Detail
          default: auto
      type: object
      required:
        - type
      title: ResponseInputImage
    ResponseInputFile:
      properties:
        cache_control:
          anyOf:
            - $ref: '#/components/schemas/CacheControl'
            - type: 'null'
        prompt_cache_breakpoint:
          anyOf:
            - $ref: '#/components/schemas/PromptCacheBreakpoint'
            - type: 'null'
        type:
          type: string
          const: input_file
          title: Type
        file_id:
          anyOf:
            - type: string
            - type: 'null'
          title: File Id
        file_url:
          anyOf:
            - type: string
            - type: 'null'
          title: File Url
        file_data:
          anyOf:
            - type: string
            - type: 'null'
          title: File Data
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
      type: object
      required:
        - type
      title: ResponseInputFile
    CacheControl:
      properties:
        type:
          type: string
          const: ephemeral
          title: Type
          description: Cache type. Currently only 'ephemeral' is supported.
        ttl:
          anyOf:
            - type: string
            - type: 'null'
          title: Ttl
          description: Optional cache time-to-live, e.g. '3600s'. Provider-dependent.
      type: object
      required:
        - type
      title: CacheControl
      description: |-
        Prompt-cache marker.

        Marks a message (or content part) as a cache boundary so that the prefix
        up to that point is stored and reused on subsequent requests, reducing
        latency and cost. Only a single contiguous cache-marked block is stored
        per request, and providers enforce a minimum token count below which
        caching is silently skipped. Silently ignored by providers that don't
        support prompt caching.
    ResponseOutputText:
      properties:
        type:
          type: string
          const: output_text
          title: Type
        text:
          type: string
          title: Text
        annotations:
          items: {}
          type: array
          title: Annotations
          default: []
      type: object
      required:
        - type
        - text
      title: ResponseOutputText
    ResponseOutputRefusal:
      properties:
        type:
          type: string
          const: refusal
          title: Type
        refusal:
          type: string
          title: Refusal
      type: object
      required:
        - type
        - refusal
      title: ResponseOutputRefusal
    PromptCacheBreakpoint:
      properties:
        mode:
          anyOf:
            - type: string
              const: explicit
            - type: string
            - type: 'null'
          title: Mode
          description: >-
            Breakpoint mode. Currently only "explicit" is defined; the known
            value is advertised in the schema but not enforced, so a new
            provider value works without an Eden AI release. Leave unset for the
            provider default.
      additionalProperties: true
      type: object
      title: PromptCacheBreakpoint
      description: >-
        Marks the end of a reusable prompt prefix (OpenAI GPT-5.6 and newer).


        Set it on the last content part of the stable prefix you want cached:
        the prompt

        up to and including that part is stored and reused on later requests
        that share it,

        reducing latency and cost. Providers enforce a minimum token count below
        which

        caching is skipped. Ignored by models that don't support explicit cache
        breakpoints.
  securitySchemes:
    AuthBearer:
      type: http
      scheme: bearer

````