Chat-beeldanalyse-interface aanmaken (streaming/niet-streaming)

Deze interface ondersteunt multimodale invoer en stelt gebruikers in staat om in een gesprek zowel tekst als afbeeldings-URL's te versturen. Op basis van de prompt en de inhoud van de afbeelding genereert het model een passend antwoord. Streaming-uitvoer wordt ondersteund voor een soepelere interactie-ervaring.

Endpoint: https://api.codingplanx.ai/v1/chat/completions
HTTP-methode: POST
Officiële referentie: OpenAI Chat Completion API

Verzoekparameters

Header-parameters

Parameter	Verplicht	Type	Voorbeeldwaarde	Beschrijving
Content-Type	Ja	string	`application/json`	Formaat van de request body
Accept	Ja	string	`application/json`	Formaat van de response
Authorization	Nee	string	`Bearer {{YOUR_API_KEY}}`	API-sleutel voor authenticatie

Body-parameters

Parameter	Type	Verplicht	Standaardwaarde	Beschrijving
model	string	Ja	-	Het gebruikte model-ID (zoals `gpt-4o`, `gpt-4-vision-preview`).
messages	array	Ja	-	De lijst met berichten in het gesprek tot nu toe. Zie hieronder voor de structuur van `messages`.
stream	boolean	Nee	`false`	Of streaming-uitvoer wordt ingeschakeld. Indien ingeschakeld, worden Server-Sent Events (SSE) verzonden.
temperature	number	Nee	`1`	Sampling-temperatuur (0-2). Hoe hoger, hoe willekeuriger; hoe lager, hoe consistenter.
top_p	number	Nee	`1`	Kans voor nucleus sampling. Het wordt aanbevolen om slechts één van `temperature` of `top_p` aan te passen.
max_tokens	integer	Nee	inf	Het maximale aantal tokens dat in de chat-completion wordt gegenereerd.
n	integer	Nee	`1`	Hoeveel completions voor elk invoerbericht moeten worden gegenereerd.
presence_penalty	number	Nee	`0`	(-2.0 tot 2.0) Positieve waarden vergroten de kans dat het model nieuwe onderwerpen aansnijdt.
frequency_penalty	number	Nee	`0`	(-2.0 tot 2.0) Positieve waarden verminderen de kans dat het model dezelfde woorden herhaalt.
response_format	object	Nee	-	Specificeert het uitvoerformaat, bijvoorbeeld `{"type": "json_object"}`.
stop	string/array	Nee	null	Sequenties waarop het genereren moet stoppen (maximaal 4).
user	string	Nee	-	Unieke identificatie van de eindgebruiker, gebruikt voor het monitoren van misbruik.

Structuur van het `messages`-object

Elk item in de berichtenlijst bevat de volgende velden:

role: (string) De rol, mogelijk system, user, assistant, tool.
content: (string of array) De inhoud van het bericht.
- In beeldanalyse-modus is content een array met objecten van het type text en image_url.

Voorbeeldverzoek

Gemengd verzoek met tekst en beeldanalyse (JSON)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "Je bent een professionele assistent voor beeldanalyse."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "Wat staat er op deze afbeelding? Beschrijf het gedetailleerd."
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png"
                    }
                }
            ]
        }
    ],
    "stream": true
}

Uitleg van de response

Niet-streaming response (`stream: false`)

Parameter	Type	Beschrijving
id	string	De unieke identificatie van deze aanvraag.
object	string	Het objecttype, meestal `chat.completion`.
created	integer	Tijdstempel van aanmaak (in seconden).
choices	array	De lijst met door het model gegenereerde opties.
choices[n].message	object	Het door het model geretourneerde berichtobject (met `role` en `content`).
choices[n].finish_reason	string	Reden van stoppen (zoals `stop`, `length`).
usage	object	Statistieken over tokengebruik.

Voorbeeldresponse

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Deze afbeelding toont een rustig meer met op de achtergrond een bergketen."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 35,
        "total_tokens": 155
    }
}

Streaming response (`stream: true`)

Wanneer stream op true staat, retourneert de interface text/event-stream. Elke regel begint met data: en bevat een JSON-string. Het laatste bericht is data: [DONE].

FAQ (Veelgestelde vragen)

Q1: Hoe kan ik een afbeelding uploaden in plaats van een URL te gebruiken?
A: Deze interface ondersteunt voornamelijk afbeeldings-URL's. Als u alleen een lokale afbeelding hebt, wordt aangeraden deze eerst te uploaden naar een image host of objectopslag (OSS), of de afbeelding om te zetten naar een Base64-gecodeerde string in het formaat data:image/jpeg;base64,{base64_encode_data} en deze in het veld url te plaatsen.

Q2: Waarom krijg ik bij een streaming-verzoek geen usage-statistieken terug?
A: In het standaard OpenAI-compatibele streamingprotocol wordt usage meestal alleen in het laatste datablock geretourneerd, of via een speciale parameter zoals stream_options. Controleer of uw modelversie het teruggeven van tokenstatistieken tijdens streaming ondersteunt.

Q3: Welke beperkingen gelden voor afbeeldingsgrootte en -indeling bij beeldanalyse?
A: Over het algemeen worden PNG, JPEG, WEBP en GIF (niet-geanimeerd) ondersteund. Het wordt aanbevolen dat de afbeeldingsgrootte niet groter is dan 20MB. Voor de beste herkenningsresultaten wordt een resolutie van minimaal 512x512 aanbevolen.

Q4: Wat moet ik doen als mijn verzoek de foutmelding "401 Unauthorized" geeft?
A: Controleer of u de Authorization-header correct hebt meegegeven, in het formaat Bearer gevolgd door uw API KEY, en zorg ervoor dat de sleutel geldig is en voldoende saldo heeft.

Q5: Heeft de parameter temperature invloed op beeldanalyse?
A: Ja. temperature beïnvloedt hoe creatief de taal van het model is bij het beschrijven van afbeeldingen. Als u een zeer objectieve en nauwkeurige beschrijving wilt, stel dan een lagere waarde in (zoals 0.2); als u een levendigere en creatievere beschrijving wilt, gebruik dan een hogere waarde (zoals 0.8).

Q6: Hoe kan ik meerdere afbeeldingen tegelijk laten analyseren?
A: U kunt meerdere objecten van het type image_url toevoegen in de array messages.content. Het model zal proberen deze afbeeldingen gezamenlijk te begrijpen.